PSR-5: Especificación de Documentación de PHPDoc
Objetivo de PSR-5
El objetivo de PSR-5 era definir un estándar claro y uniforme para la documentación de código PHP utilizando PHPDoc. Esto incluía la sintaxis, las etiquetas y las prácticas recomendadas para garantizar que la documentación fuera consistente, fácil de leer y mantenible.
Directrices de PSR-5
Formato Básico de PHPDoc
Un bloque de PHPDoc comienza con / y termina con */. Los comentarios pueden incluir descripciones, etiquetas específicas y tipos de datos.
/**
* Breve descripción.
*
* Descripción detallada.
*
* @tag1 valor1
* @tag2 valor2
*/Etiquetas Comunes
Algunas de las etiquetas más comunes en PHPDoc, que también habrían sido parte del estándar PSR-5, incluyen:
- @param: Describe un parámetro de una función o método.
- @return: Describe el valor de retorno de una función o método.
- @var: Describe la propiedad de una clase o una variable.
- @throws: Indica las excepciones que una función o método puede lanzar.
- @deprecated: Marca un elemento como obsoleto.
- @author: Indica el autor del código.
- @see: Proporciona una referencia a otra parte del código o documentación.
Ejemplos de Uso
Documentación de una Función
/**
* Calcula la suma de dos números.
*
* Esta función toma dos números como entrada y devuelve su suma.
*
* @param int $a El primer número.
* @param int $b El segundo número.
* @return int La suma de $a y $b.
*/
function suma($a, $b) {
return $a + $b;
}Documentación de una Clase y sus Propiedades
/**
* Clase Usuario que representa a un usuario en el sistema.
*
* @package MiAplicacion
*/
class Usuario {
/**
* El nombre del usuario.
*
* @var string
*/
public $nombre;
/**
* La edad del usuario.
*
* @var int
*/
public $edad;
/**
* Constructor de la clase Usuario.
*
* @param string $nombre El nombre del usuario.
* @param int $edad La edad del usuario.
*/
public function __construct($nombre, $edad) {
$this->nombre = $nombre;
$this->edad = $edad;
}
}Buenas Prácticas
- Consistencia: Mantén un estilo de documentación consistente a lo largo del código.
- Claridad: Asegúrate de que las descripciones sean claras y comprensibles.
- Actualización: Mantén la documentación actualizada con los cambios en el código.
- Detallado pero Conciso: Proporciona suficiente detalle sin ser redundante.
Herramientas de PHPDoc
Existen herramientas que pueden ayudar a generar y validar la documentación PHPDoc:
- phpDocumentor: Una herramienta que genera documentación en HTML a partir de comentarios PHPDoc.
- PHPStan: Un analizador estático que puede validar la documentación PHPDoc en tu código.
- Psalm: Otro analizador estático que también puede verificar la consistencia de la documentación PHPDoc.
Conclusión
Aunque PSR-5 no fue adoptada oficialmente, la propuesta tenía la intención de proporcionar una guía estandarizada para la documentación de código PHP utilizando PHPDoc. Adoptar estas prácticas y etiquetas comunes en tu documentación PHPDoc puede mejorar significativamente la claridad y mantenibilidad de tu código. Las herramientas disponibles pueden facilitar la generación y validación de la documentación, asegurando que tu proyecto esté bien documentado y sea fácil de entender para otros desarrolladores.
Jorge García
Fullstack developer