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).