La documentación de un proyecto de software es tan importante como su código. Una buena documentación nos facilita en gran medida el mantenimiento futuro de la aplicación. Si además estamos trabajando en equipo es muy útil saber lo que hacen las partes que desarrollan otras personas, sobretodo si tenemos que utilizarlas en nuestra parte.
Para ayudarnos existe la aplicación PhpDocumentor, que nos permite generar automáticamente una buena documentación de nuestro código, de una forma parecida a como lo hace JavaDoc. Mediante comentarios y unas etiquetas especiales podemos definir de forma sencilla que hace cada clase, cada método y cada función de nuestro código.
Los elementos que pueden ser documentados son:
- define
- function
- class
- class vars
- include/require/include_once/require_once
- global variables
Además se puede incluir documentación global a nivel de fichero y clase mediante la marca @package
Documentación para classes y archivos
Marca | Significado |
@access | Si @access es ‘private’ no se genera documentación para el elemento (a menos que se indique explícitamente). Muy interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados). |
@author | Autor del código |
@copyright | Información sobre derechos |
@deprecated | Para indicar que el elemento no debería utilizarse, ya que en futuras versiones podría no estar disponible. |
@example | Permite especificar la ruta hasta un fichero con código PHP. phpDocumentor se encarga de mostrar el código resaltado (syntax-highlighted). |
@ignore | Evita que phpDocumentor documente un determinado elemento. |
@internal inline {@internal}} |
Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores. |
@link inline {@link} |
Para incluir un enlace (http://…) a un determinado recurso. |
@see | Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento). |
@since | Permite indicar que el elemento está disponible desde una determinada versión del paquete o distribución. |
@version | Versión actual del elemento |
1
Documentación para funciones y métodos
Marca | Significado |
@global | Permite especificar el uso de variables globales dentro de la función. |
@param | Parámetros que recibe la función. Formato: * @param tipo $nombre_var comentario |
@return | Valor devuelto por la función. Formato: * @return tipo comentario |
1
Para terminar este post decir que mi IDE favorito PHPDesigner está
perfectamente integrado con PHPDocumentor tanto para documentar como
para compilar la documentación. Esta es una de las razones por las que
es mi IDE favorito.
0 comentarios:
Publicar un comentario