Diferencia entre revisiones de «Instalación e uso de phpDocumentor»

De MediaWiki
Ir a la navegación Ir a la búsqueda
Línea 32: Línea 32:
 
* [https://docs.phpdoc.org/latest/getting-started/installing.html Documentación oficial de Instalación de phpDocumentor]
 
* [https://docs.phpdoc.org/latest/getting-started/installing.html Documentación oficial de Instalación de phpDocumentor]
  
−
= Uso =
+
= 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)
 +
{
 +
}
 +
 
 +
* 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 .
 +
* Line 13 shows the closing sequence */, which is the same as that for a multi-line comment (/* .. */).
 +
 
 
* [https://docs.phpdoc.org/latest/getting-started/your-first-set-of-documentation.html Exemplo de uso de phpDocumentor]
 
* [https://docs.phpdoc.org/latest/getting-started/your-first-set-of-documentation.html Exemplo de uso de phpDocumentor]
  

Revisión del 07:22 15 nov 2020

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

Descargando el 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 run --rm -v $(pwd):/data phpdoc/phpdoc:3

Usando docker

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 .
* Line 13 shows the closing sequence */, which is the same as that for a multi-line comment (/* .. */).

* 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
Obtenido de «https://wiki.cifprodolfoucha.es/index.php?title=Instalación_e_uso_de_phpDocumentor&oldid=11381»