Docco o como documentar tus proyectos

Hoy ha sido un día de estar rebuscando entre las diferentes formas de generar documentación en un proyecto automáticamente. Hay mil maneras, pero al final me he decantado por Docco por su facilidad de instalación y porque los ficheros que genera son estéticamente agradables de ver.

¿Qué pasos he de seguir para instalar y probar docco?

  1. Nodejs: Descargarlo de aquí e instalarlo.
  2. Docco: Instalar docco mediante la instrucción npm. En windows será npm install -g docco (El link del docco y su información es este)
  3. Ejecutar docco contra el código que quieras documentar mediante la instrucción “docco archivoadocumentar”. Te creará la documentación en docs/

El resultado de pasar el proceso por el php que teníamos es el siguiente:

docco_resultado

Nota: Otra opción que intenté usar es la del equivalente de docco en php, que es el sourceMakeup, pero la verdad es que, al probarlo después de descargarlo directamente de su página, da errores notice y también de generación de archivos.

Opciones que tiene

  • Absolutamente todos los comentarios que quieren situarse a la izquierda tienen que ir precedidos por //
  • Títulos: Después del // iniciarlo con ##
  • Lista: Después del // iniciarlo con un guión –
  • Negrita: Incluir la palabra en negrita entre asteriscos **palabra**
  • Url: Se haría del tipo [Home](http://www.yises.com/)

Algo a destacar es que la versión para windows tiene un bug por el cual obliga a poner a mano todos los ficheros sobre los cuales se quiere hacer la documentación (no se puede poner nada del tipo *.php)