Ver el código de «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 [https://phpdoc.org/phpDocumentor.phar la última versión] ou [https://github.com/phpDocumentor/phpDocumentor/releases 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
* [https://hub.docker.com/r/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 =
<pre>
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)
 {
 }
</pre>

* 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''.

* [https://docs.phpdoc.org/latest/getting-started/your-first-set-of-documentation.html Exemplo de uso de phpDocumentor]

= Posible tarefa =
# Instala a ferramenta seguindo a documentación oficial (ou calquera outra que te 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.

= Referencias =

= Créditos =
* [https://docs.phpdoc.org/3.0/guide/getting-started/installing.html#installation Instalación]
* [https://docs.phpdoc.org/3.0/guide/getting-started/your-first-set-of-documentation.html A túa primeira documentación con phpDocumentor]