La documentación de código es algo sumamente importante en el gremio de desarrollador de aplicaciones; todos lo sabemos. Es necesario dejar comentarios entre sentencias y poner una buena descripción de qué va a hacer nuestras clases en las cabeceras de los archivos para poder recordar para qué hiciste lo que hiciste y saber cómo funciona tu app por dentro después de un tiempo sin trabajar en ella.

Pero con eso no basta… ¿De qué sirve una buena documentación si no tenemos una manera amigable de leerla? Es muy común perder tiempo en buscar un método en concreto de una clase en concreta en un proyecto que contenga muchísimos archivos; esto no es eficiente.

¿Cómo solucionar esto? Con un generador de documentación.

Un generador de documentación no es más que una utilidad que parsea todos tus archivos fuentes en busca de etiquetas especiales que definen la descripción, los parámetros, el valor que se devuelve, etc. en un método. En el caso específico de Objective-C, hay varias utilidades de este tipo… Pero yo me quedo con appledoc.

Appledoc es una solución muy elegante ya que genera DocSets; paquetes de documentación, como los que ofrece Apple en el Organizer del Xcode.

Solo necesitas bajar la última versión estable del proyecto desde GitHub y compilarlo. Debes copiar el contenido de la carpeta Templates a ~/Library/Application Support/appledoc/ y el ejecutable obtenido de la compilación a /usr/bin/ para tenerlo siempre a mano.

Una vez lo tengas debes ejecutar este comando desde la carpeta del proyecto:

Si no establecéis un path para la salida, se instalará automáticamente en la documentación de Xcode.

¿Y vosotros? ¿Cómo hacéis para documentar vuestros proyectos?

Descarga – appledoc en GitHub