Instalación e uso de phpDocumentor

Consideracións pedagóxicas

Este material pode ser utilizado:

• No módulo Despregue de Aplicacións Web do Ciclo de Desenvolvemento de Aplicacións web
  • No "BC6. Documentación das aplicacións web e sistemas de control de versión"
    • Ferramentas externas para a xeración de documentación: instalación, configuración e uso
    • Formatos estándar para a documentación. Uso de linguaxes de marcas na documentación de aplicacións web.
• No módulo Contornos de Desenvolvemento do Ciclo de Desenvolvemento de Aplicacións web

Considerecións previas

• É convinte un coñecemento básico de programación e a linguaxe PHP

Instalación

Instalación usando Phibe

$ phive install phpDocumentor

Instalación descargando o PHAR

Descargando la última versión ou unha específica
Invocando PHP co ficheiro phar como parámetro:
$ php phpDocumentor.phar -d . -t docs/api

Para Mac e Linux, previamente:

Marcar o ficheiro como executable 
$ chmod +x phpDocumentor.phar
Movelo a ruta do cartafol bin
$ mv phpDocumentor.phar /usr/local/bin/phpDocumentor

Instalación con docker

Se tes docker instalado:

$ docker pull phpdoc/phpdoc
$ docker run --rm -v $(pwd):/data phpdoc/phpdoc

• Instalación de phpDocumentor vía docker

Instalación con phpPear

apt-get install php-pear

Por defecto Apache busca no directorio /var/www para o contido web, con cal antes da instalación de phpDocumentor deberíamos dicirlle a pear que é aquí onde queremos que phpDocumentor traballe; podese configurar este ou otro directorio, sempre e cando sxea accesible polo servidor web:

#pear config-set data_dir /var/www

A continuación podemos instalar phpDocumentor coas súas dependencias:
#pear install --alldeps PhpDocumentor

Ou directamente podemos descargar o paquete mediante:
#wget sourceforge.net/projects/phpdocu/files/PhpDoc/phpDocumentor-1.4.3/PhpDocumentor-1.4.3.tgz y luego descomprimirlo.

Unha vez rematado o proceso de instalación necesitamos crear un directorio de saída para phpDocumentor, e cambiar o propietario do devandito directorio a www-data, de xeito que poida traballar nesta carpeta sen ninguhna limitación.

Por exemplo podemos realizar o siguiente:
#mkdir /var/www/docs
#chown www-data /var/www/docs/

Se desde un navegador tecleamos http://localhost/PhpDocumentor/ deberíamos comprobar que a instalación foi correcta e temos phpDocumentor listo para funcionar.

Documentando o código

Exemplo
Un DocBlock é semellante a isto:

<?php
/**
 * A summary informing the user what the associated element does.
 *
 * A *description*, that can span multiple lines, to go _in-depth_ into
 * the details of this element and to provide some background information
 * or textual references.
 *
 * @param string $myArgument With a *description* of this argument,
 *                           these may also span multiple lines.
 *
 * @return void
 */
 function myFunction($myArgument)
 {
 }

• Liña 2 - DocBlock comeza con esta secuencia /**
• Liña 3 ten un exemplo de Summary
• Liñas 5, 6 e 7 amosa un exemplo de unha Description, que pode ocupar múltiples liñas e ser formateada coa sintaxe Markdown
• Liñas 9 e 12 amosa que podes incluir etiquetas nos teus DocBlocks para engadir información adicional acerca do seguinte elemento. Neste exemplo declaramos que o argumento $myArgument é de tipo string cunha descripción do que representa este argumento; e declaramos que o valor de retorno de este método e void, que quere dicir que non se devolverá ningún valor
• Liña 13 amosa a secuencia de peche */

Xenerando a documentación

O uso básico de phpDocumentor é facilitando unha ruta de entrada usando a liña de comandos:

-d para un cartafol
-f para un ficheiro 

E indicar que a saída da documentación sexa no cartafol que prefiras co parámetro -t.

Por exemple
$ phpdoc -d ./src -t ./docs/api

O que fai o exemplo é escanear todos os ficheiros no directorio src e os seus subdirectorios, realizar unha análise e xerar unha web que conterá toda a documentación na ruta docs/api.

No caso de omitir o parámetro -t, a saída será escrita nun subcartafol output.

• Exemplo de uso de phpDocumentor

Posible tarefa

Instala e comproba o funcionamento de PhpDocumentor

1. Instala a ferramenta seguindo a documentación oficial (ou calquera outra que che sirva de axuda).
2. Documenta unha función a que se lle pasa dous valores e devolve a suma dos mesmos
3. Entrega un documento explicando para qué sirve phpDocumentor, e os pasos seguidos na instalación e xeración de documentación
4. Amosa captura de pantalla do resultado obtido.

Solución

• 

  Código con comentarios

• 

  Xeración de documentación

Alternativas

• Doxygen
• Javadoc 1 2

Créditos

• Instalación
• A túa primeira documentación con phpDocumentor
• Información de phpDocumentor da Junta de Andalucía