Ir al contenido principal

miframe-docsimple: Documentación siempre en línea

Uno de los grandes dolores de cabeza que tuve al programar fue el no poder acceder en línea a la documentación del código y como tal, poca importancia se le dio a la documentación efectiva del mismo. Como resultado, la revisión de código resultaba un completo martirio cuando no recordabas los detalles de alguna clase o función o no tenías a mano al programador que lo escribió para explicarlo.

DocSimple es una clase PHP que se encarga de leer un script e intenta recuperar la documentación del mismo, siempre que esta se haga siguiendo las directrices del modelo Javadoc, adaptado según se describe en la página de la librería phpDocumentor. Por ejemplo: 

/**
 * Primera línea es un resumen de mifunction_php.
 * A continuación la descripción. Cada párrafo termina en punto o con una
 * línea en blanco.
 * @param string $argument1 Esta es la descripción del primer argumento.
 * @return string Texto de salida.
 */
function mifunction_php(string $argument1) { … return $text; }

Aunque por defecto está configurada para interpretar bloques de comentario en scripts PHP, puede modificarse para obtener documentación de scripts en otros lenguajes que manejen un esquema similar de documentación.

Estos son algunos de los potenciales usos de esta librería:

  • Recuperar la información de documentación de un script para su manipulación.
  • Presentar la documentación de un script para consulta en línea, ya sea empleando el generador HTML interno de la clase o uno propio a partir de la información recuperada.
  • Facilitar la generación de documentación en formato PDF o similar (el proceso de exportar en formatos PDF u otros no está incluido en esta versión, por lo que este proceso queda en manos del usuario a partir de la información recuperada).
  • Usarlo en el control de versiones para que se valide la documentación de los scripts nuevos y/o modificados y permitir o no el commit de los mismos.

Elementos de documentación soportados

Estos son los elementos (tags) de documentación que son evaluados con especial énfasis por la clase DocSimple:

  • author: Nombre del autor del elemento asociado. Requerido a nivel de script (primer comentario encontrado), opcional si se desea en alguna o todas de las funciones/métodos contenidas en el mismo.
  • link: Relación entre el elemento asociado y una página web (referencias).
  • param: (Sólo para funciones, métodos) Cada argumento de una función o método, uno por tag. Formato esperado: [tipo: string, int, bool, etc.][espacio][nombre][espacio][descripción (opcional)].
  • return: (Sólo para funciones, métodos) Valor retornado por una función o método. Formato esperado: [tipo resultado][espacio][descripción (opcional)].
  • since: Indica en qué versión el elemento asociado estuvo disponible. Si no se documenta a nivel de script, el sistema lo reporta con la fecha de creación del script.
  • uses: Indica referencias a otros elementos/scripts/librerías. Formato esperado: [nombre librería sin espacios][espacio][descripción (opcional)].
  • version: Versión actual del elemento estructural (a nivel de script más que de funciones o métodos).

Otros elementos serán detectados y reportados por la clase aunque no se les dará un manejo por defecto a los mismos.

Más información

Código básico para uso de la clase: 

$doc = new \miFrame\Utils\DocSimple();
$documento = $doc->getDocumentationHTML($filename, true);

Pueden consultar más información, detalles y opciones de descarga de esta clase en: 

https://github.com/jjmejia/miframe-docsimple 

Por supuesto, esta clase todavía puede mejorarse. Algunas posibles mejoras para futuras versiones incluyen:

  • Permitir la definición de funciones a ejecutar al detectar tags de documentación.
  • Depurar el formato en texto simple, usado en el arreglo de elementos de documentacuón retornado. 
  • Manejo de caché externo para agilizar consultas reiterativas.

Importante!  

Esta librería forma parte de los módulos PHP incluidos en micode-manager.

Etiquetas:

Comentarios

Publicar un comentario

Entradas populares de este blog

Manejo de recursos HTML para tus páginas web con PHP

Déjame saber si te resulta familiar esta situación: páginas web que descargan el mismo recurso (sean estilos CSS o código Javascript) más de una vez o incluyen recursos remotos que tardan una eternidad en cada descarga. Yo lo he visto en más de una ocasión y no es difícil imaginar el porqué ocurre. Un desarrollador incluye el recurso de estilos que necesita su segmento de código y otro hace lo mismo, sin reparar (o sin que siquiera importe) que comparten el mismo recurso. En otro escenario muy común, acostumbran incluir muchos recursos remotos, con lo que el rendimiento de la página depende de lo rápido que responda dicho recurso. ¿Puede hacerse algo al respecto? Claro que si. Vamos a crear una clase en PHP que se encargue de administrar estos recursos y que nos facilite su despliegue en la página sin repeticiones . ¿Y respecto a la demora en la carga de recursos remotos? Atendamos una cosa por vez, porque como dicen por ahí: «Vísteme despacio, que tengo prisa». Administrando ...
Publicar un comentario
Leer más

Manejo de clases globales únicas en PHP

¿Cómo acceder desde cualquier script en tu proyecto a Clases y/o funciones de uso común? Este puede ser una de las primeras directrices a establecer para cualquier proyecto porque siempre, siempre , sea en  PHP  u otro lenguaje, será necesario usar recursos comunes. En PHP existen diferentes alternativas para su manejo, ya sea por medio de variables globales o de clases/objetos estáticos. A continuación consideraremos una propuesta para este manejo. Creación de recursos globales Para ilustrar esta solución, partimos de la necesidad de implementar una librería para manejo de servicios relacionados con el servidor Web, que de forma amigable nos permita disponer de información como: Valores almacenados de la variable superglobal $_SERVER de PHP. Valores asociados a la consulta realizada por el usuario, por Ej. la dirección IP del usuario o la URL ingresada. Valores asociados al servidor web usado, por Ej. la dirección IP del servidor o la ubicación del script que ej...
Publicar un comentario
Leer más

¿Qué tan bueno es realmente el “foreach” en PHP?

Como toda buena historia, esta comienza hace algún tiempo. El que fuera mi jefe por allá en la primera década del 2000, realmente odiaba (y mucho) el uso del foreach en el código PHP . Prefería que usáramos alguna alternativa diferente, alguna combinación del  for o del while . ¿Por qué? Ve tú a saber, nunca fue abierto respecto a las razones de su aprensión hacia ese constructor propio del lenguaje. Pero antes de continuar, veamos qué es y para qué nos puede servir. Arreglos, tenían que ser arreglos ¿Qué es foreach ? De acuerdo al manual de PHP , su definición es la siguiente: El constructor foreach proporciona un modo sencillo de iterar sobre arrays . foreach funciona sólo sobre arrays y objetos , y emitirá un error al intentar usarlo con una variable de un tipo diferente de datos o una variable no inicializada. Para su uso correcto existen dos sintaxis validas, a saber: foreach (expresión_array as $value) { ... } foreach (expresión_array as $key => $value) { ....
Publicar un comentario
Leer más