Instalación e uso de phpDocumentor
Sumario
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 "BC6. Documentación das aplicacións web e sistemas de control de versión"
- 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 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.
Posible tarefa
Instala e comproba o funcionamento de PhpDocumentor
- Instala a ferramenta seguindo a documentación oficial (ou calquera outra que che sirva de axuda).
- Documenta unha función a que se lle pasa dous valores e devolve a suma dos mesmos
- Entrega un documento explicando para qué sirve phpDocumentor, e os pasos seguidos na instalación e xeración de documentación
- Amosa captura de pantalla do resultado obtido.
Solución
Código con comentarios
Xeración de documentación
