Cómo documentar tu código con PHPDoc

Cómo documentar tu código con PHPDoc

1. ¿Qué es PHPDoc

PHPDoc es un formato de comentarios que utiliza etiquetas especiales (tags) para describir la finalidad, parámetros, tipo de retorno y otra información relevante sobre el código. Estas anotaciones pueden ser procesadas por herramientas como phpDocumentor o integradas en IDEs para mejorar la experiencia de desarrollo.

2. Beneficios de usar PHPDoc

• Claridad: Proporciona descripciones claras de la API interna o pública.
• Autocompletado: Los IDEs pueden ofrecer sugerencias basadas en las anotaciones.
• Generación automática: Documentación en HTML o PDF mediante herramientas especializadas.
• Mantenimiento: Facilita la incorporación de nuevos desarrolladores al proyecto.
• Calidad: Incentiva a mantener una interfaz consistente y tipos bien definidos.

3. Sintaxis básica de PHPDoc

Un bloque PHPDoc se inicia con /, cada línea comienza con y finaliza con /. Ejemplo mínimo:

/
  Breve descripción de la función.
 
  Descripción detallada que puede ocupar varias líneas.
 
  @param int   a Número de elementos.
  @param array b Valores a procesar.
  @return bool  Resultado de la operación.
 /
function procesar(int a, array b): bool {
    // ...
}
  

4. Etiquetas principales

Etiqueta	Descripción
@param	Define el tipo y nombre de un parámetro de función o método.
@return	Indica el tipo de valor devuelto por la función o método.
@var	Documenta el tipo de una propiedad en una clase.
@throws	Especifica las excepciones que puede lanzar el método.
@see	Referencia otras clases, métodos o documentación externa.
@deprecated	Marca un elemento como obsoleto, indicando alternativas.

5. Ejemplos prácticos

5.1 Documentar una clase

/
  Gestor de usuarios de la aplicación.
 
  Permite crear, actualizar y eliminar usuarios.
 
  @package AppServices
 /
class UserManager {
    /
      Almacenamiento de datos de usuario.
     
      @var PDO
     /
    private db

    /
      Constructor.
     
      @param PDO db Conexión a base de datos.
     /
    public function __construct(PDO db) {
        this->db = db
    }

    /
      Obtiene un usuario por su ID.
     
      @param int id Identificador único del usuario.
      @return arraynull Datos del usuario o null si no existe.
      @throws Exception Si ocurre un error en la consulta.
     /
    public function getUserById(int id): array {
        // ...
    }
}
  

5.2 Documentar una propiedad compleja

class Report {
    /
      Datos de ventas por mes.
     
      @var array
     /
    private monthlySales = []
}
  

6. Buenas prácticas

1. Descripciones breves pero precisas: Empieza con una línea clara y, si es necesario, añade detalles en párrafos siguientes.
2. Tipado correcto: Usa tipos nativos (int, string) y fully qualified cuando hagas referencia a clases externas.
3. Actualiza la documentación: Cada vez que cambies la firma de un método, revisa sus comentarios.
4. No describas el “cómo”, enfócate en el “qué” y el “por qué”. El código debe mostrar la implementación.
5. Sigue convenciones: Mantén un estilo homogéneo en todo el proyecto.

7. Herramientas y generación automática

• phpDocumentor: La herramienta más popular. Genera sitio web estático con la documentación HTML. Enlace oficial: phpdoc.org.
• ApiGen: Crea documentación similar a PHP manual (apigen.org).
• Doxygen: Aunque no es exclusivo de PHP, soporta PHPDoc y múltiples lenguajes (doxygen.nl).

8. Integración en IDEs y editores

IDE como PhpStorm y editores como Visual Studio Code ofrecen autocompletado e inspección de errores basados en PHPDoc. Instala extensiones como PHP DocBlocker en VSCode para generar plantillas automáticamente.

9. Personalización de plantillas

Las herramientas de documentación permiten ajustar estilos y estructuras. Con phpDocumentor puedes definir tu propio tema mediante --template y editar archivos de plantilla en .twig.

10. Conclusión

Adoptar PHPDoc es una inversión en la calidad y sostenibilidad de tus proyectos de PHP. Al combinar una sintaxis clara, buenas prácticas y herramientas automatizadas, conseguirás una documentación profesional que acelera el desarrollo, evita errores y facilita el trabajo en equipo.