UD 3 Documentando el código de PHP

Documentación.

H Se ha probado y documentado el código.

Índice

En el siguiente apartado veremos diferentes aspectos, enfoques y herramientas de la documentación de nuestro código PHP

Markdown
PHP Documentor
Extensiones VSC

Hasta ahora en el curso hemos autodocumentado nuestro código y creado ficheros de markdown (Readme) siguiendo buenas prácticas de programación actuales, indagaremos otras herramientas útiles para este apartado

Markdown/GitHub

Documentar proyectos PHP utilizando Markdown y GitHub es un enfoque moderno y eficiente para mantener la información del proyecto accesible, clara y organizada. GitHub utiliza un archivo README.md como punto central de la documentación, el cual se escribe en Markdown, un lenguaje de marcado simple para formatear texto.

1. Planifica la estructura del archivo `README.md`

Un archivo README.md debe proporcionar información clave sobre el proyecto de forma clara y concisa. Incluye los siguientes elementos:

Título del Proyecto
Descripción Breve
Instalación
Uso
Estructura del Proyecto
Contribuciones
Licencia
Contacto o Información Adicional

2. Redacta el archivo `README.md`

Un ejemplo práctico de un archivo README.md para un proyecto PHP podría ser:

# Sistema de Gestión de Tareas

Este es un proyecto PHP para gestionar tareas. Permite crear, editar y eliminar tareas utilizando una interfaz web.

## Características

- Gestión de tareas (CRUD)
- Almacenamiento en una base de datos MySQL
- Arquitectura MVC

## Requisitos

- PHP 8.0 o superior
- Composer
- Servidor Apache o Nginx
- MySQL

## Instalación

1. Clona este repositorio:
   ```bash
   git clone https://github.com/tuusuario/gestion-tareas.git

Instala las dependencias con Composer:

composer install

3. Configura la base de datos:

Crea una base de datos MySQL.
Copia el archivo .env.example y renómbralo como .env.
Configura las credenciales de la base de datos en el archivo .env.
Inicia el servidor de desarrollo:

php -S localhost:8000

Uso

Accede a http://localhost:8000 en tu navegador.
Agrega, edita o elimina tareas según sea necesario.

Estructura del Proyecto

├── public/
│   ├── index.php        # Punto de entrada del proyecto
├── src/
│   ├── Controllers/     # Lógica de controladores
│   ├── Models/          # Lógica de modelos
│   ├── Views/           # Plantillas HTML
├── vendor/              # Dependencias de Composer
├── .env.example         # Archivo de ejemplo para configuración
├── composer.json        # Dependencias del proyecto
├── README.md            # Documentación principal

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, sigue estos pasos:

Haz un fork del proyecto.
Crea una nueva rama:
```
git checkout -b mi-nueva-funcionalidad
```

Realiza tus cambios y haz commit:

git commit -m "Agrega nueva funcionalidad"

Envía tus cambios al repositorio remoto:
```
git push origin mi-nueva-funcionalidad
```
Abre un Pull Request en GitHub.

Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más información.

---

### **3. Configura GitHub para mostrar el `README.md`**

1. **Sube el proyecto a GitHub:**
   - Inicia un repositorio local:
     ```bash
     git init
     ```
   - Agrega los archivos al repositorio:
     ```bash
     git add .
     ```
   - Haz commit:
     ```bash
     git commit -m "Primera versión del proyecto"
     ```
   - Conecta el repositorio local con GitHub:
     ```bash
     git remote add origin https://github.com/tuusuario/tu-repositorio.git
     ```
   - Envía los cambios:
     ```bash
     git push -u origin main
     ```

2. **Asegúrate de que el archivo `README.md` esté en la raíz del repositorio.** GitHub lo mostrará automáticamente en la página principal del repositorio.

---

### **4. Mejora el archivo README.md con elementos visuales**

GitHub permite usar Markdown enriquecido para mejorar la legibilidad:

- **Imágenes:** Para agregar capturas de pantalla del proyecto.
  ```markdown
  ![Captura de Pantalla](ruta/a/captura.png)

Enlaces: Para referencias externas o internas.

[Documentación oficial de PHP](https://www.php.net/docs.php)

- Código resaltado: Muestra fragmentos de código PHP o de otros lenguajes.

<?php
echo "¡Hola, mundo!";

5. Mantén la documentación actualizada

Actualiza el README.md con cada cambio importante en el proyecto.
Usa issues y pull requests en GitHub para gestionar actualizaciones y comentarios sobre la documentación.

6. Extiende la documentación

Si el proyecto crece, puedes crear una carpeta llamada docs/ en el repositorio para alojar documentación más detallada. Por ejemplo:

Guía de instalación avanzada
API Docs
Guías para contribuciones

Estructura de ejemplo:

docs/
├── api.md
├── advanced-installation.md
├── contributing.md

En el archivo README.md, agrega enlaces a estos documentos:

- [Documentación de la API](docs/api.md)
- [Guía de Instalación Avanzada](docs/advanced-installation.md)
- [Contribuciones](docs/contributing.md)

Ventajas de este enfoque

Colaboración eficiente: Markdown es fácil de leer y escribir, y GitHub permite la colaboración en tiempo real.
Organización: La estructura clara ayuda a los desarrolladores y usuarios a encontrar información fácilmente.
Accesibilidad: La documentación es pública y accesible desde cualquier lugar con conexión a internet.

Este enfoque garantiza que el proyecto esté bien documentado y sea fácil de usar por desarrolladores y usuarios finales.

Documentación del código/PHPDoc

Usar y generar documentación con herramientas como PHPDoc es útil para documentar una clase, sus propiedades y métodos en PHP. Puedes estructurar PHPDoc en un contexto de clase y documentar cada elemento para obtener una referencia completa del código.

1731765674226

<?php

/**
 * Clase que representa un Círculo.
 *
 * Esta clase permite crear y manipular un círculo, 
 * ofreciendo métodos para calcular su área y perímetro.
 */
class Circulo {

    /**
     * @var float $radio Radio del círculo.
     */
    private $radio;

    /**
     * Constructor de la clase Círculo.
     *
     * @param float $radio El radio inicial del círculo.
     * @throws InvalidArgumentException Si el radio es negativo.
     */
    public function __construct(float $radio) {
        if ($radio < 0) {
            throw new InvalidArgumentException("El radio no puede ser negativo.");
        }
        $this->radio = $radio;
    }

    /**
     * Establece el radio del círculo.
     *
     * @param float $radio El nuevo radio del círculo.
     * @throws InvalidArgumentException Si el radio es negativo.
     */
    public function setRadio(float $radio) {
        if ($radio < 0) {
            throw new InvalidArgumentException("El radio no puede ser negativo.");
        }
        $this->radio = $radio;
    }

    /**
     * Obtiene el radio del círculo.
     *
     * @return float El radio actual del círculo.
     */
    public function getRadio(): float {
        return $this->radio;
    }

    /**
     * Calcula el área del círculo.
     *
     * @return float El área del círculo.
     */
    public function calcularArea(): float {
        return pi() * pow($this->radio, 2);
    }

    /**
     * Calcula el perímetro del círculo.
     *
     * @return float El perímetro del círculo.
     */
    public function calcularPerimetro(): float {
        return 2 * pi() * $this->radio;
    }
}

// Ejemplo de uso
$circulo = new Circulo(5);
echo "Área: " . $circulo->calcularArea() . "\n";
echo "Perímetro: " . $circulo->calcularPerimetro() . "\n";

Apartados:

PHPDoc de la clase (class Circulo): Describe el propósito general de la clase.
Propiedad ($radio): La propiedad privada se documenta usando @var, indicando el tipo de dato.
Métodos:
Constructor (__construct): Describe el propósito del constructor e incluye @param y @throws.
Métodos de acceso (setRadio y getRadio): Documentan los parámetros y valor de retorno.
Métodos de cálculo (calcularArea y calcularPerimetro): Explican el propósito de cada método y documentan el valor de retorno usando @return.

Instalar y usar PHP Doc

Usaremos el gestor de depencias y paquetes COMPOSER, la web oficial para Linux, Docker y otras versiones es: https://phpdoc.org/

Para instalar PHPDoc en Windows sigue estos pasos:

1. Instalar Composer

PHPDoc se gestiona con Composer, así que primero debes instalarlo:

Descargar Composer:
Ve al sitio oficial: https://getcomposer.org/download/
Descarga y ejecuta el instalador de Composer para Windows.
Configurar la instalación:
Durante la instalación, asegúrate de seleccionar el ejecutable de PHP en tu sistema (debe estar instalado previamente y configurado en tu PATH).
Verificar la instalación:
Abre una terminal o el símbolo del sistema y escribe:
```
composer --version
```
Si ves un número de versión, Composer está instalado correctamente.

2. Instalar PHPDocumentor

Con Composer instalado, puedes instalar PHPDocumentor globalmente o como dependencia de tu proyecto:

Opción A: Instalación global

Abre una terminal y ejecuta:

composer global require phpdocumentor/phpdocumentor

Asegúrate de que el directorio de Composer global está en tu PATH:
Por defecto, está en C:\Users\TuUsuario\AppData\Roaming\Composer\vendor\bin.
Agrega este directorio a las variables de entorno si es necesario.

1731738241682

Opción B: Instalación en un proyecto específico

Navega al directorio de tu proyecto y ejecuta:

composer require --dev phpdocumentor/phpdocumentor

(Nos podría preguntar si confiamos en el plugin de symfony, le decimos que si (y)

1731738352075

3. Crear un Archivo PHP de Prueba

Crea un archivo PHP en tu proyecto. Por ejemplo, ejemplo.php:

<?php

/**
 * Calcula el área de un círculo.
 *
 * @param float $radio El radio del círculo.
 * @return float El área del círculo.
 */
function calcularArea(float $radio): float {
    return pi() * pow($radio, 2);
}

4. Generar Documentación con PHPDoc

Abre la terminal y navega al directorio de tu proyecto.
Ejecuta el siguiente comando para generar la documentación:

phpdoc -d . -t docs

-d .: Especifica el directorio actual como la fuente de los archivos PHP.
-t docs: Indica que la salida de la documentación se guardará en el directorio docs.

5. Verificar la Documentación Generada

Una vez completado el proceso, ve al directorio docs.
Abre el archivo index.html en un navegador para ver la documentación generada.

Solución de Problemas

Si el comando phpdoc no funciona, verifica que el directorio global de Composer está en tu PATH.
Asegúrate de usar una versión de PHP compatible (PHPDocumentor requiere PHP 7.4 o superior).

1731665912794

Extensiones VSC

Otra forma útil de documentar nuestro código es mediante extensiones, nos basaremos para ello en el siguiente tutorial

Tutorial documentar el código

Extensiones, puedes probarlas y usar la que te resulte más útil

PHP DocBlocker
PHP Doc Extender
Montlify

1731765979805

1731766072078

Ejemplo con Mintlify

Para probar Mintlify selecciona la función o bloque que quieres documentar y activa el botón GENERATE DOCS que aparece activando la extensión

1731766252939

Verás, en inglés, como te ha documentado el código

 /**
     * The function calculates the perimeter of a circle based on its radius.
     * 
     * @return float the calculated perimeter of a circle based on the formula 2 * π * radius.
     */
    public function calcularPerimetro2(): float {
        return 2 * pi() * $this->radio;
    }

Referencias

PHP Documentation

W3Schools

Artículo documentación PHP

Artículo web epsilon