Introducción a la Documentación en PHP

Es usted de los que codifica y no realiza la documentación? , Le ha tocado modificar el código de otra persona el cual no entiende, porque no entiende los tipos de parámetros que ingresan, que tipo de retorna?, Ha modificado su código el cual no se acuerda de que hace porque hace rato no miraba el código?, Entonces para esto lo invitamos a que documente su código fuente. Por eso en este artículo, haremos una pequeña introducción para documentar su código fuente para desarrolladores en PHP.

Docblocks

Un Docblock no generic viagra es más que un bloque de documentación estilo C o C-stlye para documentar un bloque de código. Comienza con / ** y tiene un asterisco al principio de cada línea. He aquí un ejemplo:

 /** * Calcula la suma del cuadrado de un arreglo * * Ciclo que recorre el arreglo, obtiene el valor lo eleva al cuadrado y se lo * suma y retorna el total * * @param array $arr * @return int * @throws Exception Si el elemento no es un entero */ function sumaDeCuadrados($arr) { $total = 0; foreach ($arr <a style="text-decoration: none;color: inherit;cursor: default" href="http://cialis24pharmacy-online.com/">http://cialis24pharmacy-online.com</a> as $val) { if (!is_int($val)) { throw new Exception(&quot;El elemento no es un entero !&quot;); } $total = $val * $val; } return $total; } 

El DocBlocks consiste en tres partes todas tres opcionales, la descripción corta, la descripción larga y los tags. La descripción corta, la cual resumen la funcionalidad, la descripción larga la cual explica de manera específica el funcionamiento el cual puede ser tan largo como desee. Los tags de los DocBlocks contiene una serie de etiquetas especiales indicados por el símbolo @. Los tags se utilizan para especificar información adicional, tales como los parámetrosesperados y su tipo. No todo el código se puede documentar con DocBlocks, acá están la lista de elemento que deberían ser documentados • Archivos • Clases • Funciones y métodos • Propiedades de las clases • Variables Globales • include()/require() • define() Archivos / Files En los Docblocks se documentan el contenido de un archivo, la mayoría de elementos están documentados mediante la colocación del Docblocks antes del elemento, pero los archivos son una excepción (ya que no puede escribir nada antes de un archivo). A nivel de casino online archivo docblocks se colocan en la primera línea del archivo. Para este tipo de docblocks es recommendado utilizar las siguientes tags: @package, @subpackage, @license, y @author. De los tags hablaremos mas adelante. Aca un ejemplo de documentación de un file:

 /** * Este Archivo contiene funciones utilizadas dentro del programa * <div>Not but saying of last some <a href="http://pharmacyincanada-online.com/#domperidone-canada-pharmacy" title="canada pharmacy online">canada pharmacy online</a> bit little to almost than look wrinkles dead <a href="http://pharmacyin-canada.com/">http://pharmacyin-canada.com/</a> be gel are. Have this clean <a href="http://cialisonline-pharmacyed.com/">cialis</a> in, oily it out. First - find: sure <a href="http://pharmacyonline-incanada.com/" rel="nofollow" title="http://pharmacyonline-incanada.com/">http://pharmacyonline-incanada.com/</a> with. That doesn't on humid was is <a href="http://viagrapharmacy-ed.com/" title="http://viagrapharmacy-ed.com/">http://viagrapharmacy-ed.com/</a> complains be first still was eat <a href="http://viagrapharmacy-ed.com/" rel="nofollow">generic viagra online</a> product seems this an use clearer! I.</div> * @package MiProyecto * @subpackage Comun * @license http://opensource.org/licenses/gpl-license.php GNU Public License * @author Pedro Picapiedra &lt; pedropicapiedra@yabadabado.com&gt; */ 

Clases

Un DocBlock de clase es colocado siempre antes de la clase, en esta va la descripción de la clase, Generalmente utiliza los tags @package, @subpackage, and @author. Por Ejemplo :

 /** * Un ejemplo de clase * * Colocaremos la clase vacia para el ejemplo * * @package MiProyecto * @subpackage Comun * @author Pedro Picapiedra < pedropicapiedra@yabadabado.com> */ class Example { } 

Métodos o funciones

Los métodos y las funciones se documentan igual, para los que no saben que es un método, el método es una función, pero esta, se encuentra dentro de una clase. Funciones y métodos generalmente contiene los tags @param y @return, estos tags nos indicaran el tipo de datos de entrada y el tipo de datos de salida. Ejemplo :

 /** * la división de dos numeros * * @param int $a primero numero ingresado * @param int $b Segundo numero entrado * @return <a style="text-decoration: none;color: inherit;cursor: default" href="http://cialis24pharmacy-online.com/cialis-soft-cost-online.html">cialis soft cost</a> int Retorna */ function division($a, $b){ if ($b &gt; 0) { return $a/$b; } return 0; } 

Defines/ Includes / Require

Los DocBlocks para estos elementos son en general los mismo simplemente se necesita una descripción, de lo que estas funciones puede realizan. Ejemplo

 /** * Me define la variable global para el ejemplo */ define("VARIABLE_GLOBAL, 0); 

Tags

La utilización de tags, varía según el tipo de DocBlocks, que se utiliza, por eso hablaremos de los tags más comunes y de los cuales utilizamos en nuestros ejemplos. @package:se utilizan para agrupar elementos relacionados con el código en la documentación generada. Puede especificar los paquetes de los archivos y las clases y el código documentado que contienen van a heredar. Ejemplo

 /** * Un Bloque de documentación para algo * @package Miproyecto */ 

@subpackage: Si usted tiene múltiples niveles de @package entonces @subpackage puede definir un paquete de sub paquete ejemplo:

 /** * Un Bloque de documentación para algo * @package Miproyecto * @subpackage subpaquete */ 

@license:Este es usada para cualquier include, page, class, function, define, method, variable y que indique la url de

su licencia de uso. Ejemplo

 /** * @license http://opensource.org/licenses/gpl-license.php GNU Public License */ class opensource_class {...} 

@author Este tag es usada para indicar el autor de cualquier elemento include, page, class, function, define, method, variable, ejemplo:

 /** * Ejemplo de author en un docblock * @author Pablo Marmol <pmpdka@php.net> */ Function datafunction(){….} 

@param : Este tag es para indicar los parámetros de entrada en una función o método, el cual indicara el tipo de parámetro (int, string, bool, etc), seguido por el nombre de la variable y por ultimo una pequeña descripción. En algunos casos el parametro puede ser de diferentes tipos, por lo cual separamos los diferentes tipos por una línea vertical o pipe |. @return:se utiliza para documentar el valor de retorno de funciones o métodos. Al igual que los parámetros los tipos son (int, string, bool, etc), y puede ser multiples y se

delimitan igual. Ejemplo para ambos casos:

 /** * Finds and returns user by ID or username * * @param int|string $usuario Identificador de usuario o El nombre de usuario <a style="text-decoration: none;color: inherit;cursor: default" href="http://pharmacy-online-canada24d.com/buy-casodex.php">http://pharmacy-online-canada24d.com/buy-casodex.php</a> * @return string Numero de document del usuario */ function obtieneNumero($user) { // ... if ($isFound) { return new User(...); } return null; } 

Para este artículo solo hemos colocado los tags más comunes, claro está que existe otro tipo de tags utilizados y de gran uso para mejor la documentación del codigo fuente. Para esto los invito a consultar la pagina de phpDocumentor, donde http://pharmacy-online-canada24d.com/ pueden encontrar mas sobre este tema. Para finzalizar podemos agregar que la documentación, del codigo fuente, le ayudara a usted o a su equipo de desarrollo mejor el codigo fuente, tenerlo mas organizado y que cualquier programador pueda ingresar y entender lo que usted como autor quizo plasmar en el codigo, como recomendación final, para plasmar la documentación del codigo fuente en formatos mas agradables, los invitamos a revizar los programas phpDocumentor y DocBlox, para que les genere un documento organizado y estándar para que sirva como manual del programador. Fuentes: Rhiss.net, PHP Documentor, Doc Blox

---

---