Documentación con phpDocumentor¶

phpDocumentor es la herramienta de facto para documentar el código PHP. Es similar en propósito y funcionamiento a Javadoc. Así pues, es un herramienta que facilita la documentación del código PHP, creando un sitio web con el API de la aplicación. Se basa en el uso de anotaciones sobre los docblocks. Para ponerlo en marcha, en nuestro caso nos decantaremos por utilizar la imagen que ya existe de Docker.

Instalación como binario¶

Otra opción es seguir los pasos que recomienda la documentación oficial para instalarlo como un ejecutable, que son descargar el archivo phpDocumentor.phar y darles permisos de ejecución. Para ello, se deben seguir los siguientes pasos:

Descargar el archivo .phar:

wget https://phpdoc.org/phpDocumentor.phar

Asignarle permisos de ejecución:
```
chmod +x phpDocumentor.phar
```
Moverlo al directorio binario del sistema para facilitar su uso:
```
mv phpDocumentor.phar /usr/local/bin/phpdoc
```
Verificar la instalación:
```
phpdoc --version
```

Una vez instalado, desde el raíz del proyecto, suponiendo que tenemos nuestro código dentro de app y que queremos la documentación dentro de docs/api ejecutamos:

phpdoc -d ./app -t docs/api

Donde:

-d especifica el directorio que contiene el código fuente a documentar.
-t especifica el directorio donde se generará la documentación.

Uso en Docker¶

Para quienes prefieren Docker, se puede utilizar la imagen oficial de phpDocumentor. Por ejemplo:

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

A dicho comando, le adjuntaremos los diferentes parámetros que admite phpDocumentor, por ejemplo:

# Muestra la versión
docker run --rm -v "$(pwd)":/data phpdoc/phpdoc:3 --version
# Mediante -d se indica el origen a parsear
# Mediante -t se indica el destino donde generar la documentación
docker run --rm -v "$(pwd)":/data phpdoc/phpdoc:3 -d ./src/app -t ./docs/api

DocBlock¶

Los docblock on bloques de comentarios especiales que se colocan justo antes de un elemento del código (clase, método, propiedad, etc.). Su estructura básica es:

<?php
/**
* *Sumario*, una sola línea
*
* *Descripción* que puede utilizar varias líneas
* y que ofrece detalles del elemento o referencias
* para ampliar la información
*
* @param string $miArgumento con una *descripción* del argumento
* que puede usar varias líneas.
*
* @return void
*/
function miFuncion(tipo $miArgumento)
{
}

Documentando el código¶

En todos los elementos, ademas del sumario y/o descripción, pondremos:

En las clases:
- @author nombre
- @package ruta del namespace
En las propiedades:
- @var tipo descripción
En los métodos:
- @param tipo $nombre descripción
- @throws ClaseException descripción
- @return tipo descripción

Veámoslo con un ejemplo. Supongamos que tenemos una clase que representa un cliente:

Cliente.php

<?php
/**
* Clase que representa un cliente
* 
* El cliente se encarga de almacenar los soportes que tiene alquilado,
* de manera que podemos alquilar y devolver productos mediante las operaciones
* homónimas.
* 
* @package Dwes\Videoclub\Model
* @author Ginés López <g.lopezgarcia2@edu.gva.es>
*/
class Cliente {

    public string $nombre; 
    private string $numero;

    /**
    * Colección de soportes alquilados
    * @var array<Soporte> 
    */
    private $soportesAlquilados[];

    /**
    * Comprueba si el soporte recibido ya lo tiene alquilado el cliente
    * @param Soporte $soporte Soporte a comprobar
    * @return bool true si lo tiene alquilado
    */
    public function tieneAlquilado(Soporte $soporte) : bool { 
        // ...
    }
}

Si generamos la documentación y abrimos con un navegador el archivo docs/api/index.html podremos navegar hasta la clase Cliente.

Actividades¶

AC 505. (RA4 RA5 / CE4f CE5h / IC1 / 3p) - Comprueba que en el contenedor de Docker funciona phpDocumentor. Ejecuta phpdoc sobre tu proyecto Monologos y verifica el API que se crea. Comenta tanto la clase como los métodos, y posteriormente, vuelve a ejecutar phpdoc.
RE 506. (RA4 RA5 / CE4f CE5h / IC2 / 5p) - Es momento de iniciar la elaboración de la documentación, una fase clave dentro del desarrollo integral del reto. Este proceso permitirá registrar las decisiones adoptadas, el enfoque aplicado y los resultados alcanzados, lo que facilitará su comprensión. Además, recuerda que esta parte también será evaluada como parte del Reto 02.

Se hará uso de la siguiente lista de cotejo:
- Uso de Composer para gestionar dependencias.
- Pruebas unitarias realizadas con PHPUnit para al menos dos clases.
- Implementación de registros de actividad y errores con Monolog.
- Generación de documentación técnica con phpDocumentor.
- Informe técnico entregado (decisiones, estructura, manual de uso).
- Video demostrativo del funcionamiento del prototipo entregado.
Sigue trabajando en el reto

Recuerda que el Reto 02 sigue en marcha a nivel de desarrollo, no olvides que tienes que entregarlo en tiempo y forma con todo lo que se solicita en el enunciado.