Para leer este post debes haber tenido que al menos pasar por algunas de las siguientes situaciones:

• Haber programado al menos el reloj despertador
• Haber tenido que explicarle al menos a tu mama como se programaba la tele
• Haber tenido que explicarle a algún cliente por correo que su página web es mejor sin flash
• Haber tenido que realizar algún manual de usuario
• Haber tenido que explicar por msn como conectar un pc a internet
• Realizar un mapa a alguien para que llegue a alguna parte
• Haber escrito a una polola en una carta las razones por las que no quieres estar con ella
• Haber tenido que dejar un papel explicando que el almuerzo lo dejaste listo y que en la olla grande esta el plato fuerte, en la chica la sopa y en el refri la ensalada
• Escribir un cheque

¿Qué tiene que ver todo esto con Natural Docs?

, Bueno si se fijan, todas las opciones exceptuando las 2 primeras, son acciones en las que has tenido que dejar constancia, tanto en papel, como en digital, de algún procedimiento o acción que realizaste.  Ahora por otra parte, cuando programas o realizas proyectos de software también debemos dejar constancia de lo que hemos realizado, esto se realiza por varias razones: Mejorar la comprensión del problema, Tener registro de lo que se realizó, Poder mejorarlo en el futuro,  Pensar en los que tomaran el código en futuras generaciones( Uno de los mas importantes :p), etc. Todo lindo hasta aquí pero ¿A los computines les gusta realizar esta tarea?, la respuesta obviamente es no, muchas veces llega a ser un martirio, otras no hay tiempo y otras simple y llanamente nos hacemos los lesos y no la hacemos . ¿Alternativas?, si,  buscar metodologías agiles de desarrollo, las cuales no se basan( no se mal entienda, no las dejan de lado) en la documentación y prefieren dar prioridad a escribir el código, la comunicación con el cliente entre otras. En mi trabajo nosotros utilizamos estas formas de trabajar, pero esto trae consigo que muchas veces no tienes idea nisiquiera de cuál es la magnitud de lo que estás desarrollando y el código que están realizando llega a ser mostruosamente grande.   Por todas estas razones una forma de crear documentación y no “invadir” en demasía al programador su “valioso” tiempo es utilizar los mismos comentarios que el utiliza en su código para generar una documentación que permite observar funciones, clases, métodos, con sus respectivos atributos y otras cosas que puedan tener.

Ahora a lo que vinimos, despues de esa introducción, vamos a revisar uno software que te toma los comentarios en el código y los transforma en una documentación de muy buena calidad .

Natural Docs

Desarrollado por Greg Valure es un generador de documentación escrito en PERL. Su forma de uso es muy simple( Suponiendo que estas en linux y tienes instalado PERL) bajamos el archivo comprimido desde aquí(en la versión estable actual 1.4).  Una vez que descomprimimos el interior te darás cuenta que posee una serie de archivos y carpetas,junta todo en una carpeta por ejemplo con nombre “NaturalDocs“. Ahora le das permiso de ejecución al archivo NaturalDocs ( chmod 755 NaturalDocs), con esto ya estamos casi listos para tener nuestra documentación, pero aún faltan algunas cosas por responder.

¿Soporta todos los lenguajes de programación?

Casi , bueno en realidad en la página de NaturalDocs aparece que soporta 19 lenguajes, pero existe un truco, si leen bien la documentación existe la posibilidad de que se agreguen mas lenguajes de manera muy simple, solo debes en un archivo de configuración darle la extención de los archivos y la forma en que se comenta.

¿Los comentarios no deben tener alguna estructura?

Jejeejej, creian que todo iba a ser tan fácil, pero no se preocupen no es la gran cosa. Por ejemplo si queremos comentar una clase

/*
Class: Counter
A class that manages an incrementing counter.
*/
class Counter
{
public:
/*
Constructor: Counter
Initializes the object.
*/
Counter()
{ value = 0; };
/*
Function: Value
Returns the value of the counter.
*/
int Value()
{ return value; };
/*
Function: Increment
Adds one to the counter.
*/
void Increment()
{ value++; };
protected:
/*
Variable: value
The counter's value.
*/
int value;
};

Como ven no es nada del otro mundo y estoy seguro que muchos de ustedes ya usan comentarios parecidos, ahora existen muchas otras formas de realizar esto y darle mas potencia a la documentación por ejemplo miren con una función

/*
* Function: Multiplicar
*
* Multiplica dos enteros.
*
* Parameters:
*    x - El primer entero.
*    y - El segundo entero.
*
* Returns:
*    El producto de ambos enteros.
*
* Ver también:
*
*/
int Multiplicar (int x, int y)
{  return x * y;  };

Ahora le dimos una breve descripción de la funcion, que los parametros que recibe son x e y, que es lo que retorna y que esa función esta relacionada con otra, la idea es que todo eso despues queda reflejado en la documentación generada.

La gamma de diferentes cosas que puedes realizar con los comentarios descubranlos en la pagina del soft.

Ahora como ejecuto tal maravilla.

Bueno esto es muy simple, anteriormente le habíamos dado permisos de escritura al script NaturalDocs, bueno ahora debemos ejecutarlo con los siguientes parámetros como mínimo

NaturalDocs -i [input (source) directory]
-o [output format] [output directory]
-p [project directory]
[options]

Como eso no dice mucho un ejemplo

NaturalDocs -i home/tuto/My Project/Source
-o FramedHTML home/tuto/My Project/Docs
-p home/tuto/My Project/Natural Docs

Un poco de explicación: La primera dirección que le damos es la carpeta donde tenemos el código que queremos documentar, la segunda direccion es la carpeta donde guardaremos nuestra documentación y la tercera es una carpeta que debemos crear para que NaturalDocs escriba unos archivos( como una carpeta temporal). Existen muchas otras opciones que puedes agregarle pero eso véanlo aca y eso es todo, el soft se encarga de todo, es muy configurable y puedes crear documentaciones muy profesionales ,algunos ejemplo aquí.

Ahora una última pregunta para terminar

¿Existen otros documentadores de código?
Por supuesto y algunos muy o más buenos que este( lo publiqué porque a mi me gusta mucho este soft), por ejemplo aquí puedes ver una comparativa entre los más populares

Bueno eso por hoy

El link de la página es LINK

Espero les sirva

saludo tuto