Costa Rica PHP

¿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: {@*}