Que son los PHPDocs
¿Que es PHPDocs?
Es un estándar para escribir comentarios en el código similar a Javadoc. PHPDocs es el estándar de auto-documentación para el lenguaje de PHP.
Ejemplo completo | Documentacion generada con PHPDocumentor
Un ejemplo simple:
/**
* Título simple
*
* Descripción de la clase, archivo, función…
*
* @package Paquete al cual pertenece
* @subpackage Sub Paquete
* @author Pablo Viquez
* @version $Id: index.php 524 2008-01-30 20:15:23Z pviquez $
*/
Etiquetas (tags) básicas
Una explicación de la sintaxis básica, además de las etiquetas que son requeridas por PHPDocs.
@package
Que es: Especifica el paquete de clases o funciones que se definen dentro.
Uso:
@package NOMBRE_PAQUETE
Notas
Se puede usar en dos lugares:
- Nivel de página. Define funciones, inclusiones, requerimientos (includes / requires)
- Nivel de clase. Clase sus variables y métodos.
@subpackage
Que es:Especifica el sub-grupo de clases o funciones que se definen dentro.
Uso
@subpackage NOMBRE_SUB_PAQUETE
Notas:
Si la etiqueta @package no existe, esta será ignorada.
@var
Que es: Especifica el tipo de dato de una variable de una clase
Uso
@var TIPO_DE_DATO
Notas
Se usa para miembros de una clase y el tipo de dato debe ser un tipo válido.
Algunos tipos validos:
- bool – Variables true/false
- string – Cadenas de caracteres
- int – Enteros
- mixed – Variable
- array – Arreglos/Vectores
@author
Que es: Especifica el autor del elemento
Uso
@author <email@address.com>
Notas Puede ser usado en todo lugar y el texto que se encuentre dentro de “<>” se tratará de interpretar como correo electrónico.
@todo
Que es: Cambios al documento que deben de ser hechos en el futuro
Uso:
@todo Una línea explicando el "por-hacer"
@version
Que es: Versión del documento
Uso
@version 123
Notas: Se puede mezclar la versión con un control de versiones, con SVN, automáticamente nos pondría la revisión del documento, fecha de la última modificación y el autor de ella.
Para esto se usa:
@version $Id$
En SVN desde la línea de comando (aplica para Windows también):
svn propset svn:keywords Id <nombre_del_archivo>
@see
Que es: Despliega un link a la documentación de un elemento
Uso
@see Clase_Usada
Notas Esta se usa para elementos SOLO dentro de la documentación, no para links externos, se le puede decir dónde buscar:
- :: Dentro de cual clase debe buscar el elemento. Clase::$nombreVariable
- () Si esta presente al final de un elemento, le dice al compilador que busque por una función. ejemplo()
- $ Se le dice que busque por una variable dentro de la clase
@link
Que es: Despliega un hyperlink a una URL en la documentación
Uso
@link http://www.costaricaphp.org
Notas Puede ser usada en cualquier elemento
@example
Que es: Incluye un ejemplo externo con la sintaxis demarcada
Uso
@example <ruta_completa_del_archivo || ruta_relativa_del_archivo>
Notas: Se usa para compilar junto con la documentación algún archivo que se requiere desplegar el código de una manera fácil de leer.
Ejemplo Inline example
Que es: La habilidad de especificar código dentro de un comentario sin incluir archivos.
Uso
/**
* Esta función fue creada para desplegar un ejemplo PHPDocs
*
* Puede ser usada de manera siguiente:
* <code>
* $usuario = new Usuario();
* echo $usuario->setNombre('Pablo');
* </code>
*
*/
Trucos
- Cuando genere la documentación PHPDocs, siempre busque y revise el archivo errors.html
- Puede usar algunos elementos de HTML dentro de la documentación.
- <p>, <b>, <li>, <ol>, <ul>, <code>, <pre>
- Si por alguna razón desea agregar <b> en la documentación haga: <<b>>
- Para cerrar un comentario dentro de la documentación use: {@*}
