PHPDOC
PHPDoc es un estándar de documentación para php que permite agregar comentarios estructurados en el código fuente para describir clases, métodos, funciones, parámetros, y otros elementos. Estos comentarios son procesados por herramientas como phpDocumentor para generar documentación automática en formatos como HTML o PDF. Es similar a Javadoc en Java.
Usa bloques de comentarios con etiquetas específicas, como @param, @return, @throws, etc., para describir el propósito y comportamiento del código. Los comentarios PHPDoc comienzan con /** y terminan con */.facilitando la documentación automática mejorando la legibilidad del código y ayuda en la colaboración entre desarrolladores. Ejemplo:
/**
* Calcula el factorial de un número.
*
* @param int $n El número para calcular el factorial.
* @return int El factorial del número.
* @throws InvalidArgumentException Si el número es negativo.
*/
function factorial($n) {
if ($n < 0) {
throw new InvalidArgumentException("El número no puede ser negativo.");
}
return $n == 0 ? 1 : $n * factorial($n - 1);
}
Etiquetas comunes
- @param [tipo] $nombre Descripción: Describe un parámetro.
- @return [tipo] Descripción: Indica el tipo y propósito del valor retornado.
- @throws [Excepción] Descripción: Documenta excepciones que puede lanzar la función.
- @var [tipo] Descripción: Describe el tipo de una variable o propiedad.
- @see: Referencia a otros métodos o documentación.