Especificación para la documentación del código fuente en PHP de

Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 1/11
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
ELABORO:
RESPONSABLE
Jorge Iván Meza Martínez
REVISÓ:
APROBÓ:
Grupo de Sistemas
Grupo de Sistemas
<[email protected]
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
CARGO
FECHA
1.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 2/11
Consultor Sistemas
Consultores de Sistemas
Consultores de Sistemas
24/07/2007
24/07/2007
24/07/2007
Introducción.
El presente documento especifica la sintaxis básica de los comentarios requeridos para
generar la documentación técnica del código de un proyecto PHP basado en la
herramienta phpDocumentor desarrollada para tal fin. Se especifican también los
formatos o plantillas específicos para documentar las diferentes entidades
computacionales en el código fuente de los proyectos desarrollados por la Empresa.
Respecto a la herramienta elegida para generar la documentación se especifican los
pasos requeridos para su instalación y su ejecución sobre proyectos web específicos a
documentarse.
2.
Especificación
phpDocumentor.
2.1.
general
de
los
documentos
compatibles
con
Los comentarios de documentación se enmarcan en la siguiente disposición.
/**
*
*/
Cualquier linea de comentario que no empiece por el carácter asterisco ('*') es ignorada.
2.2.
Un bloque de comentarios consta de la siguiente estructura.
/**
* Descripción corta (1 línea).
*
* Descripción larga (múltiples líneas).
*
* Etiquetas.
*/
Los párrafos de la descripción larga pueden separarse con etiquetas <p>.
Otras etiquetas que pueden ser utilizadas son las relacionadas a continuación.
<b>
Énfasis.
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
<code>
<br>
<i>
<kbd>
<li>
<ol>
<pre>
<samp>
<ul>
<var>
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 3/11
Código fuente.
Salto de línea.
Itálica.
Entrada por teclado/pantalla.
Elemento de lista.
Lista ordenada.
Mantiene la información contenida tal cual está formateada.
Denota ejemplo.
Lista no ordenada.
Nombre de variable.
2.3.
El comentario que documenta una estructura se debe ubicar justo antes de la
declaración de dicha entidad.
Los elementos susceptibles de ser documentados obedecen a la siguiente lista.
Sentencias define[_once].
Sentencias include[_once].
Funciones.
Clases.
Métodos y atributos.
Variables globales.
Existe una estructura adicional que puede ser documentada y es el archivo de código.
Un bloque de documentación hace referencia al archivo y no a un elemento específico si
se cumple alguna de las siguientes condiciones.
1. Si el primer bloque de documentación en el archivo de código incluye la etiqueta
@package y no se encuentra sucedido por un elemento class.
2. Si el primer bloque de documentación en el archivo de código antecede a otro
bloque documentación.
2.4.
Es posible definir listas simples con líneas de comentarios que empiezan por “-”,
“+”, “#” ú
“o” y listas ordenadas que empiezan por índices seguidos por punto y
separadas por un espacio.
Es posible crear listas complejas utilizando las etiquetas <ol>/<li>.
/**
* DocBlock with nested lists
* in the tag descriptions
* @todo My Simple TODO List
*
- item 1
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 4/11
*
- item 2
*
- item 3
* @todo My Complex TODO List
*
<ol>
*
<li>item 1.0</li>
*
<li>item 2.0</li>
*
<li>item 3.0</li>
*
<ol>
*
<li>item 3.1</li>
*
<li>item 3.2</li>
*
</ol>
*
<li>item 4.0</li>
*
</ol>
*/
2.5.
Las etiquetas son opcionales y proporcionan información adicional acerca de la
entidad
documentada.
Las etiquetas constan de una palabra que las identifica precedida por el símbolo de
arroba ('@'). Cada una de las etiquetas tiene su propia lista de parámetros que se
referencia a continuación.
@abstract
Especifica que una clase, un método o una variable son abstractos.
@access public|private|protected
Determina el nivel de acceso del elemento. Si el nivel de acceso es privado no se
incluirá en la documentación.
@category nombre
Especifica la categoría a la cual pertence la entidad documentada dentro del
paquete.
@author nombre [<dirección de correo electrónico>]
Autor del elemento documentado.
@copyright información
Información de derechos de autor (copyright).
@deprecated información
Determina que el elemento es obsoleto y no debería utilizarse ya que puede ser
retirado en el futuro cercano.
@example ruta/archivo descripción
Incluye un archivo de ejemplo externo con sintaxis resaltada.
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 5/11
@final
Determina que el elemento es final y por lo tanto no puede ser sobreescrito o crear
subclases de él.
@global tipo_de_datos $nombre_de_variable (para globales/atributos)
@global tipo_retorno descripción
(para funciones/métodos)
Documenta una variable global o su uso en funciones y métodos.
@ignore
Evita que se realice la documentación del elemento.
@internal información_no_publicable
Especifica información que no se incluye en la documentación pública.
@license URL nombre
Muestra un hiperenlace en la documentación que referencia la licencia utilizada.
@link URL [texto]
Despliega un hiperenlace en la documentación.
@package nombre
Especifica el paquete que agrupa de manera documental las clases y funciones
especificadas.
@param tipo_de_datos $nombre_de_variable descripción
@param tipo1|tipo2|... $nombre_de_variable descripción
Describe un parámetro de un método o función.
@return tipo_de_datos descripción
@return tipo1|tipo2|... descripción
Describe el tipo de retorno de un método o función.
@see archivo|nombre_elemento|clase::método()|clase::$variable|
función()
Muestra un enlace que referencia la documentación de otros elementos.
@since información de versión o de fecha
Documenta cuando/en que versión se agregó el elemento.
@static
Especifica que el método o atributo son estáticos (de clase).
@staticvar tipo_de_datos $nombre descripción
Especifica el uso de una variable estática en un método o función.
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 6/11
@subpackage nombre_sub_paquete
Especifica el subpaquete en el que se ubican las clases o métodos definidas.
Requiere de la etiqueta @package.
@throws información_de_excepciones
Especifica las posibles excepciones lanzadas por la función o método actual.
@todo información
Documenta cambios que serán realizados en el futuro.
@uses archivo|nombre_elemento|clase::método()|clase::$variable|
función()
Muestra un enlace a la documentación de otro elemento y crea un enlace de
regreso en la documentación del elemento referenciado.
@var tipo_de_datos descripción
Documenta el tipo de datos de un atributo.
@version información_de_versión
Versión del elemento actual.
3.
Especificación práctica.
/**
* Documentación de archivo de la clase Empleado.
*
* Esta es la documentación general del archivo de código fuente, contiene
* información general relativa a los elementos contenidos en este archivo
* toda vez que puede contener clases, funciones y variables globales por
* separado, sin embargo se recomienda utilizar siempre clases (orientación a
* objetos), minimizar el uso de variables globales y crear un archivo fuente
* por cada clase implementada.
*
* @package Proyecto.Modelo.Ejemplo.Usuarios
*/
/**
* Incluye la implementación de la clase Persona requerida por la clase Empleado
*/
include_once("../lib/classes/Persona.class.php");
/**
* Almacena la información de los empleados activos de la empresa.
*/
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 7/11
$empleados = array();
/**
* Crear empleados de ejemplo para la empresa.
*
* Crea una cantidad \$c de empleados de ejemplo con información por defecto
* para realizar la demostración del uso del sistema.
*
* @package
Proyecto.Modelo.Ejemplo.Usuarios
* @author
Jorge Iván Meza Martínez <[email protected]>
* @copyright Todos los derechos reservados. FDQ. 2007.
* @global
Array $empleados
* @internal Esta información no se incluirá en la documentación por ser
*
ultra secreta.
* @param
Integer $c Cantidad de empleados a crearse.
* @return
Float Retorna la sumatoria de los salarios de los empleados
*
creados.
* @see
Empleado
* @since
Versión 1.0, revisión 20070725.
* @version
1.0
*/
function crearEmpleados($c)
{
global $empleados;
$salarioMensual = 0;
for($i=0; $i<$c; $i++)
{
$empleados[] = new Empleado("cod_{$i}", 1000*$i);
}
}
$salarioMensual = $salarioMensual + 1000*$i;
return $salarioMensual;
/**
* Es una persona que trabaja en una Empresa y recibe un salario.
*
* Permite manejar la información básica del Empleado: su identificación en
* la empresa, su fecha de vinculación y su salario.
*
* @package
Proyecto.Modelo.Ejemplo.Usuarios
* @author
Jorge Iván Meza Martínez <[email protected]>
* @copyright Todos los derechos reservados. FDQ. 2007.
* @final
* @internal Esta información no se incluirá en la documentación por ser
*
ultra secreta.
* @see
Persona
* @since
Versión 1.0, revisión 20070725.
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
* @todo
* @version
*/
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 8/11
Implementar los métodos faltantes.
1.0
final class Empleado extends Persona
{
/**
* Código del Empleado
*
* @access protected
* @since
Versión 1.0, revisión 20070725.
* @var
String Código del empleado.
*/
protected $codigo;
/**
* Salario del Empleado
*
* @access private
* @since
Versión 1.0, revisión 20070725.
* @var
Float Salario del empleado.
*/
private $salario;
/**
* Fecha de
*
* @access
* @since
* @var
*
*/
vinculación.
protected
Versión 1.0, revisión 20070725.
Date Fecha de vinculación del empleado en la empresa
(aaaa/mm/dd).
protected $fechaVinculacion;
/**
* Constructor de la clase Empleado.
*
* Crea una instancia de la clase Empleado con el Código y Salario
* especificados y la fecha actual como Fecha de Vinculación.
*
* @package
Proyecto.Modelo.Ejemplo.Usuarios
* @access
public
* @author
Jorge Iván Meza Martínez <[email protected]>
* @author
Pepito Pimentón <[email protected]>
* @internal El valor de la fecha de vinculación es asignado por defecto
*
según la norma ISO-666.
* @param
String $codigo Código del Empleado.
* @param
Float $salario Salario del Empleado.
* @since
Versión 1.0, revisión 20070725.
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
* @version
*/
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 9/11
2.0
public function __construct($codigo, $salario)
{
$this -> codigo = $codigo;
$this -> salario = $salario;
$this -> fechaVinculacion = date("m\/d\/Y");
}
/**
* Retorna el
*
* @package
* @access
* @author
* @return
*/
}
salario del Empleado.
Proyecto.Modelo.Ejemplo.Usuarios
public
Jorge Iván Meza Martínez <[email protected]>
Float Salario del Empleado.
public function obtSalario()
{
return $this -> salario;
}
4.
Generación de la documentación.
4.1. Instalación.
Descargue el archivo comprimido con la distribución de http://sourceforge.net/projects/
phpdocu/.
Descomprima el contenido de la distribución en un directorio de su elección (ejemplo: D:\
www\PhpDocumentor-1.4.0).
Cree el archivo documentar.bat en un directorio incluido en su PATH con la siguiente
especificación.
SET
SET
SET
SET
PHP_CLI=C:\dev\xampp\php\php.exe
PHP_INI=C:\dev\xampp\apache\bin\php.ini
DOCUMENTOR_PATH="D:\www\PhpDocumentor-1.4.0"
TIPO=HTML
%PHP_CLI% "-c %PHP_INI%" "%DOCUMENTOR_PATH%\phpdoc" -t %2 -o %TIPO
%:frames:default -d %1 --title %3 --parseprivate %4 --quiet
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 10/11
Edite el valor de las variables según la ubicación real de los siguientes archivos en su
estación de trabajo.



PHP_CLI
PHP_INI
DOCUMENTOR_PATH

TIPO
Ruta completa al archivo php.exe (CLI).
Ruta completa al archivo php.ini.
Ruta del directorio donde se ubicó la distribución de
phpDocumentator.
Formato de salida de la documentación.
Los posibles valores de la variable TIPO son HTML, PDF, XML ó CHM según el tipo de formato
en el que se desea generar la documentación.
4.2. Ejecución para generar la documentación.
La sintaxis para la ejecución de documentar.bat es la siguiente.
documentar.bat DIRECTORIO_ORÍGEN DIRECTORIO_DESTINO TÍTULO_DOCUMENTACIÓN TIPO_DOCUMENTACIÓN
A continuación se describen cada uno de los parámetros de línea de comando requeridos.
DIRECTORIO_ORÍGEN
archivos
 DIRECTORIO_DESTINO
Ruta completa del directorio donde se encuentran los
fuente a documentar.
Ruta completa del directorio donde se almacenará la
documentación resultante.
 TÍTULO_DOCUMENTACIÓN Título que se desea aparezca en la documentación.
 TIPO_DOCUMENTACIÓN
on para generar documentación privada (incluye
elementos
con el modificador private y el contenido de
las etiquetas
@internal) u off para generar
documentación pública.

Ejemplo:
documentar "D:\www\Ejemplo" "D:\www\Ejemplo\doc" "Documentación de ejemplo" on
La ejecución del comando anterior hace que se genere la documentación de los archivos
ubicados en D:\www\Ejemplo y se almacene en D:\www\Ejemplo\doc, con el título
Documentación de ejemplo e incluyendo información privada.
Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
5.
CODIGO: 1
EDICIÓN: 1,0
FECHA: 24/07/2007
PAGINA: 11/11
Enlaces asociados.

Sitio web de phpDocumentor
http://www.phpdoc.org/

Manual de phpDocumentor
http://manual.phpdoc.org/

Tutorial de phpDocumentor
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tut
orial_phpDocumentor.pkg.html

Sitio web de PHP
http://www.php.net/