Qué es
Lo que javadoc es para Java, phpDocumentor es para PHP: Una herramienta para generar documentación a partir del código fuente. (Ver artículo sobre
Documentación automatizada.)
Por ser dos proyectos separados, phpDocumentor no es automáticamente compatible con una nueva versión de PHP. Por ejemplo, yo tuve problemas con phpDocumentor 1.4.3 cuando instalé PHP 5.3 y volví a la versión 1.4.2 que funcionaba aunque con muchas advertencias.
Una alternativa a phpDocumentor es Doxygen que puede también documentar código PHP. Una diferencia es que doxygen es un programa, mientras phpDocumentor es una colección de código en PHP. Es decir, genera la documentación con el mismo PHP que usas para ejecutar tu propio código PHP. Por eso necesitas tener también PHP en tu máquina para poder usar phpDocumentor. Sin embargo, no necesitas instalar un servidor web.
Como instalar
phpDocumentor no es un programa sino un código fuente y, por eso, no tiene instalador. Es un archivo que descomprimes en un directorio. Para usar phpDocumentor debes abrir el fichero phpdoc.bat (en Windows) y especificar la ruta a php.exe en la variable phpCli. Por ejemplo
SET phpCli=C:\Program Files\PHP\php.exe
Como usar
Para un proyecto en concreto conviene crearse un script en que especificas todas las opciones de phpdoc.
El siguiente script es un ejemplo. Lo he utilizado para generar la documentación del mismo phpDocumentor. Antes de usarlo hay que ajustar los directorios de entrada y salida y de la instalación de PHP.
echo Generate automatic documenation for phpDocumentor echo Version from 12.6.2009 rem Directory list must be without spaces between the coma set phpdoc_dir="C:\opt\PhpDocumentor" set source_dir="C:\opt\PhpDocumentor" set target_dir="C:\doc\phpDocumentor" set title="phpDocumentor Documentation" set projects=phpDocumentor rem set output="HTML:frames:default" rem set output="HTML:frames:earthli" rem set output="HTML:frames:l0l33t" set output="HTML:frames:phpdoc.de" rem set output="HTML:frames:phpedit" rem set output="HTML:frames:phphtmllib" rem set output="HTML:frames:DOM/default" rem set output="HTML:frames:DOM/earthli" rem set output="HTML:frames:DOM/l0l33t" rem set output="HTML:frames:DOM/phpdoc.de" rem set output="HTML:frames:DOM/phphtmllib" rem set output="HTML:frames:DOM/phphtmllib" rem set output="HTML:Smarty:default" rem set output="HTML:Smarty:HandS" rem set output="HTML:Smarty:PHP" rem set output="CHM:default" rem set output="PDF:default" cd %phpdoc_dir% call phpdoc -d %source_dir% -t %target_dir% -ue on -ti %title% -pp off -po %projects% -o %output% -s off rem pause exit rem These are comments, but they will not be executed because the scripts exists before rem use phpdoc -h to see this -f --filename name of file(s) to parse ',' file1,file2. Can contain complete path and * ? wildcards -d --directory name of a directory(s) to parse directory1,directory2 -ed --examplesdir full path of the directory to look for example files from @example tags -tb --templatebase base location of all templates for this parse. -t --target path where to save the generated files -i --ignore file(s) that will be ignored, multiple separated by ','. Wildcards * and ? are ok -is --ignoresymlinks ignore symlinks to other files or directories, default is off -it --ignore-tags tags to ignore for this parse. @package, @subpackage, @access and @ignore may not be ignored. -dh --hidden set equal to on (-dh on) to descend into hidden directories (directories starting with '.'), default is off -q --quiet do not display parsing/conversion messages. Useful for cron jobs on/off default off -ue --undocumentedelements Control whether or not warnings will be shown for undocumented elements. Useful for identifying classes and methods that haven't yet been documented on/off default off -ti --title title of generated documentation, default is 'Generated Documentation' -h --help show this help message -c --useconfig Use a Config file in the users/ subdirectory for all command-line options -pp --parseprivate parse @internal and elements marked private with @access. Use on/off, default off -po --packageoutput output documentation only for selected packages. Use a comma-delimited list -dn --defaultpackagename name to use for the default package. If not specified, uses 'default' -dc --defaultcategoryname name to use for the default category. If not specified, uses 'default' -o --output output information to use separated by ','. Format: output:converter:templatedir like "HTML:frames:phpedit" -cp --converterparams dynamic parameters for a converter, separate values with commas -ct --customtags custom tags, will be recognized and put in tags[] instead of unknowntags[] -s --sourcecode generate highlighted sourcecode for every parsed file (PHP 4.3.0+ only) on/off default off -j --javadocdesc JavaDoc-compliant description parsing. Use on/off, default off (more flexibility) -p --pear Parse a PEAR-style repository (package is directory, _members are @access private) on/off default off -ric --readmeinstallchangelogSpecify custom filenames to parse like README, INSTALL or CHANGELOG files You can have multiple directories and multiple files, as well as a combination of both options
En la carpeta HTML nuevamente generado debes abrir el fichero index.html para ver la página principal de la documentación. La más práctico es crearse un enlace fuera del directorio con un nombre significativo como «Documentación de bla bla».
Puedes usar letras con acentos y otras letras no ASCII si guardas el fichero fuente (con el código) con la codificación UTF-8 (con BOM). En general no es mala idea guardar tu código como UTF-8 en lugar del habitual ISO-8859 si quieres usar otros idiomas que el inglés en los comentarios, porque phpDocumentor (y también doxygen) codifican su salida HTML en UTF-8.
phpDocumentor tiene diferentes convertidores. Cada uno compila la documentación en un formato y tema diferente (HTML, PDF, CHM). La página web de phpDocumentor muestra ejemplos de los diferentes temas visuales que permite la documentación en HTML.
Crear la documentación de phpDocumentor y tutoriales
Como ya he mencionado más arriba, phpDocumentor puede crear su propia documentación. Los ficheros fuente de esta documentación están en una subcarpeta «tutorials». Sin embargo, debes especificar el directorio raíz de phpDocumentor como directorio de entrada a phpdoc, para que se compilen estos tutoriales. (phpDocumentor no procesa documentación en «tutorials» que no esté vinculado a algún código fuente. No puedes compilar sólo tutoriales.) Como proyecto debes especificar «phpDocumentor». (Ver ejemplo abajo.)
Esta subcarpeta «tutorials» es también un ejemplo de como escribir documentación que no está directamente vinculada a algún objeto dentro del código. Estos tutoriales están escrito en un formato reducido de DocBook. Los elementos DocBook que se compilan están listado en la sección [ppage] del fichero options.ini que viene con cada convertidor. Por ejemplo, mi tema favorito «HTML:frames:earthli» está configurado por el fichero Converters/HTML/frames/templates/earthli/options.ini. Cada convertidor/tema tiene su fichero de configuración options.ini en una carpeta diferente.
Conclusión
phpDocumentor es una herramienta potente para crear documentación a partir de código fuente PHP. El formato de comentarios de documentación es fácil de aprender por ser muy parecido al formato de javadoc. (Ver lista de características de phpDocumentor.)
Una desventaja es que cuesta hacer phpDocumentor funcionar. Es un problema que desaparece una vez familiarizado con la herramienta, pero que puede causar frustración al principio. También existe una interfaz gráfica para generar la documentación pero que requiere un servidor web propiamente configurado. No está mal pero no quita el problema de tener que leer mucha documentación antes del primer éxito. En comparación el wizard de doxygen es bastante más fácil de usar.
Además, doxygen entiende varios lenguajes de programación, aunque no es capaz de ofrecer diferentes temas. Aún así vale la pena reflexionar sobre qué herramienta usar.
Referencias
- phpDocumentor – la herramienta descrita en este artículo
- Doxygen – una alternativa a phpDocumentor
- javadoc – un sistema de documentación para Java.
- PHP – el lenguaje de programación que phpDocumentor documenta.
- DocBook – un formato para escribir textos sin especificar su aparencia y que phpDocumentor usa para la documentación libre (tutoriales).
2 comentarios
Comments feed for this article
23 May 2011 a 23:32
Julian
Saludos: ¿Habra una explicacion mas visual de como instalar y usar phpDocumentor?
24 May 2011 a 22:17
trucosinformaticos
Desgraciadamente no tengo una explicación más visual, pero tampoco sé en qué podría consistir. Me acuerdo que hubo una manera de generar la documentación de forma interactiva por una página que podías generar en un servidor web en tu propio ordenador, pero nunca me pareció muy práctico.
Lo que suelo hacer es generar un script como lo he incluido en el artículo (hay que desplegarlo), ya que una vez configurado te sirve para todo el proyecto. Probablemente no tienes más remedio que leer al menos una vez todas las opciones. Luego sólo ajustas el directorio de entrada y el de salida para cada proyecto.
El script en el artículo es un fichero batch para Windows y genera la documentación del propio phpDocumentor. Lo normal sería que source_dir y target_dir apuntaran a tu proyecto.
Si usas Windows y prefieres una interfaz gráfica igual te interesa generar la documentación de PHP con doxygen (www.doxygen.org). Para Windows tiene un «wizard».