Doxygen
es un sistema de generación de documentación. Aquí voy a mostrar como
instalarlo y una mínima configuración. Además dejo un ejemplo de la
salida generada en html.
Para instalar Doxygen sólo es necesario el siguiente paquete
$ aptitude install doxygen
Para mostrar cómo configurar doxygen nos valdremos del siguiente ejemplo. Por ejemplo mi proyecto lo tengo dentro de /var/www/proyecto1
Antes de configurarlo, tenemos que crear el archivo de
configuración. Para esto nos situamos en la raíz de nuestro proyecto (o
dónde les parezca que debería ser creado el archivo de configuración) y
hacemos
:/var/www/proyecto1# doxygen -g proyect1.cfg
Este archivo, nos permite modificar los parámetros del proceso de generación de documentación para ajustarse a nuestro proyecto.
Aquí dejo algunos de los puntos más importantes de la configuración:
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
OUTPUT_DIRECTORY = /var/www/proyecto1/doc
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# The default language is English, other supported languages are:
# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian,
# Italian, Japanese, Japanese-en (Japanese with English messages), Korean,
# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian,
# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian.
OUTPUT_LANGUAGE = Spanish
# The INPUT tag can be used to specify the files and/or directories that contain
# documented source files. You may enter file names like "myfile.cpp" or
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = /var/www/proyecto1
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
# and *.h) to filter out the source-files in the directories. If left
# blank the following patterns are tested:
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py
FILE_PATTERNS = *.php
# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
# will interpret the first line (until the first dot) of a JavaDoc-style
# comment as the brief description. If set to NO, the JavaDoc
# comments will behave just like the Qt-style comments (thus requiring an
# explicit @brief command for a brief description.
JAVADOC_AUTOBRIEF = YES
En este enlace hay más ejemplos para la configuración. En sí el archivo está bastante documentado (:-P) y es suficiente por sí mismo.
Una vez terminado lo anterior nos situamos en la carpeta donde creamos el archivo de configuración, en este ejemplo en /var/www/proyecto1 y hacemos
# doxygen proyecto1.cfg
Esto generará la documentación en el directorio especificado en OUTPUT_DIRECTORY.
Dejo un pequeño ejemplo de cómo documentar una pequeña clase php.
PHP:
-
-
require_once($_SERVER[DOCUMENT_ROOT].‘/proyecto1/confi.php’);
-
/**
-
@brief Esta clase es una estructura básica de una página html
-
@author Leandro Redea
-
**/
-
class Algo{
-
/** Titulo de la página web que aparece en el browser*/
-
private $titulo = “Dinamic Web”;
-
/** Palabras claves para que los motores de búsqueda indexen esta página*/
-
private $keywords=“PHP, MySQL, GNU/Linux, *BSD”;
-
/* Pequeña descripción de la página*/
-
private $descripcion=“una simple prueba”;
-
/*Link de estilos*/
-
private $linkStyle=“http://localhost/tempo/estilo.css”;
-
/*Link de feed*/
-
private $linkFeed=“http://myhomemdz.dyndns.org/tempo/feed.php”;
-
/**
-
*Esta funcion es la cabecera
-
*/
-
public function getXhtml(){
-
echo (‘<title>’.
$this->
titulo.
“</title>\n“);
-
}
-
/** Esta funcion genera los link que se encuentran dentro de las etiquetas HEAD de una pagina web
-
*/
-
private function getLink(){
-
echo “<link rel=\”StyleSheet\” href=\”“.
$this->
linkStyle.
“\” type=\”text/css\” media=\”screen\”>”;
-
echo ‘<link rel=”alternate” type=”text/xml” title=”prueba” href=”‘.
$this->
linkFeed.
‘” />’;
-
}
-
/** Genera una parte de la página dinámica
-
@param a Es la etiqueta inferior
-
@return Devuelve el footer dentro de body */
-
public function getFooter($a){
-
//Hace muchas cosas y retorna algo
-
}
-
}
Nota: Para que los comentarios sean generados en la salida, tiene que estar dentro de las etiquetas <?php ?>
La salida se genera dentro de /var/www/proyecto1/doc. Se
crean en este caso dos carpetas una html y la otra latex. Para ver la
documentación a través de la web, bastaría escribir la siguiente url en
su browser
http://localhost/proyecto1/doc/html
Dejo una imagen de como quedaría la clase anterior generada en html.
