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

¿Querés ser parte del equipo de prueba de PHP?

El equipo de QA de PHP esta organizando un dia para probar la ultima versión de PHP (5.3/HEAD) y estan invitando a las comunidades de cada localidad a que participen. El evento se llama “PHP TestFest 2008”

Información del evento
Cuando: Sábado 10 Mayo del 2008, de 10 am hasta las 3pm.
Donde: Universidad Nacional de Costa Rica. Laboratorio de Computo, Escuela de Ciencias Agrarias. Ver mapa de Google.

¿Quienes pueden participar?

TODOS!, no importa su nivel de experiencia en PHP, siempre y cuando manejen la sintaxis. En el evento tendremos “mentores” disponibles para aclarar dudas.

¿Donde se llevará a cabo?

Se anunciará la fecha y lugar, preferiblemente un sábado en algun laboratorio durante el mes de Mayo. Si alguien desea ofrecer las instalaciones… bienvenido sea.

¿En que me beneficia?

Bueno, en primera instancia, estará ayudando a que el lenguaje sea mas robusto, además de experiencia a escribir casos de prueba mediante un framework de prueba para aplicaciones enterprise.

También que obtendrá mucha experiencia en PHP, ya que conocerá las funciones de PHP mas a fondo.

Algo importante es que entre todas las personas que escriban pruebas correctas, se estarán rifando 10 elefantesPHP. Cada prueba correcta contará, asi que entre mas pruebas, mejores opciones de ganar.

¿Es requerido saber inglés?

No, solo saber codificar PHP.

Quiero participar, ¿como me inscribo?

Si no estás subscrito a la lista de PHP, podés hacerlo en la siguiente dirección: Subscribirse Una vez inscrito, envie un correo a la lista, para apuntarte y asi planear las instalaciones.

¿Me interesa, cuando me inscribo?

Lo antes posible, asi se puede coordinar el espacio en el laboratorio.

¿Puedo anunciar este evento?

¡Claro! Se hizo este anuncio si lo desea publicar: Click aqui

El examen consiste de una serie de preguntas aleatorias relacionadas con diferentes temas que van desde las bases de PHP, hasta temas avanzados como seguridad, redes y técnicas de programación.

Algunas personas se cuestionan que tan buena es esta certificación, ya que además de evaluar temas generales, también requiere de una buena memoria para diferentes aspectos como funciones, parámetros, configuración, etc.

Lo anterior es cierto, sin embargo el tratar de obtener esta certificación expone al desarrollador a una serie de temas avanzados que podrían ser desconocidos para éste, lo cual lleva a mejores opciones y técnicas de programación.

En Costa Rica puedes obtenerla por medio de New Horizons, por un costo aproximado de $125.

Entre algunos de los materiales de estudio se encuentra el libro “Zend PHP 5 Certification Study Guide” el cual cubre gran porcentaje de los temas a evaluar. Además, puedes comprar exámenes de práctica los cuales son bastante similares al examen real. Una nota importante es que tanto el examen como las practicas únicamente están disponibles en idioma inglés.

Todos los estudiantes certificados son listados en las páginas amarillas del sitio de Zend, lo cual les da reconocimiento asi como la posibilidad de ser tomado en cuenta en opciones de empleo ofrecidas por parte de diferentes empresas.

Puedes ver la lista de ingenieros certificados de Costa Rica aquí .