Especificación para la documentación del código fuente en PHP de los proyectos de la FDQ.
←
→
Transcripción del contenido de la página
Si su navegador no muestra la página correctamente, lea el contenido de la página a continuación
CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
PAGINA: 1/11
Especificación para la documentación del código
fuente en PHP de los proyectos de la FDQ.
ELABORO: REVISÓ: APROBÓ:
RESPONSABLE Jorge Iván Meza Martínez
Grupo de Sistemas Grupo de SistemasCODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
PAGINA: 2/11
CARGO Consultores de
Consultor Sistemas Consultores de Sistemas
Sistemas
FECHA 24/07/2007
24/07/2007 24/07/2007
1. 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 general de los documentos compatibles con
phpDocumentor.
2.1. 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 .
Otras etiquetas que pueden ser utilizadas son las relacionadas a continuación.
Énfasis.CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
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 /.
/**
* DocBlock with nested lists
* in the tag descriptions
* @todo My Simple TODO List
* - item 1CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
PAGINA: 4/11
* - item 2
* - item 3
* @todo My Complex TODO List
*
* item 1.0
* item 2.0
* item 3.0
*
* item 3.1
* item 3.2
*
* item 4.0
*
*/
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 []
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.CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
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.CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
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.
*/CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
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
* @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; $iCODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
PAGINA: 8/11
* @todo Implementar los métodos faltantes.
* @version 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 vinculación.
*
* @access protected
* @since Versión 1.0, revisión 20070725.
* @var 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
* @author Pepito Pimentón
* @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.CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
PAGINA: 9/11
* @version 2.0
*/
public function __construct($codigo, $salario)
{
$this -> codigo = $codigo;
$this -> salario = $salario;
$this -> fechaVinculacion = date("m\/d\/Y");
}
/**
* Retorna el salario del Empleado.
*
* @package Proyecto.Modelo.Ejemplo.Usuarios
* @access public
* @author Jorge Iván Meza Martínez
* @return 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 PHP_CLI=C:\dev\xampp\php\php.exe
SET PHP_INI=C:\dev\xampp\apache\bin\php.ini
SET DOCUMENTOR_PATH="D:\www\PhpDocumentor-1.4.0"
SET TIPO=HTML
%PHP_CLI% "-c %PHP_INI%" "%DOCUMENTOR_PATH%\phpdoc" -t %2 -o %TIPO
%:frames:default -d %1 --title %3 --parseprivate %4 --quietCODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
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 Ruta completa al archivo php.exe (CLI).
PHP_INI Ruta completa al archivo php.ini.
DOCUMENTOR_PATH Ruta del directorio donde se ubicó la distribución de
phpDocumentator.
TIPO 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 Ruta completa del directorio donde se encuentran los
archivos fuente a documentar.
DIRECTORIO_DESTINO 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.CODIGO: 1
Especificación para la documentación del
EDICIÓN: 1,0
código fuente en PHP de los proyectos de la
FECHA: 24/07/2007
FDQ.
PAGINA: 11/11
5. 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/También puede leer
