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

Sesión de usuarios en aplicaciones web

Uno de los módulos más importantes y a la vez menospreciados cuando se aborda la tarea de crear un sitio web de servicios, ya sea para una intranet corporativa o un sistema de gestión de información ( SGI ) es la gestión y administración  requerida para una correcta implementación de sesiones de usuario. Y es que llevamos tanto tiempo usando usuarios y contraseñas en Internet, en cualquiera de sus muchas variaciones, que se asume muchas veces que esto ya forma parte del ADN de toda solución web y como tal, se destina muy poco tiempo y estudio a este apartado cuando se planifican las actividades de desarrollo. Lo cierto es que cada aplicación acostumbra desarrollar su propio esquema de manejo de sesiones y asumir que es algo superfluo puede equivaler a “pegarse un tiro en el pie”, especialmente cuando un módulo de este tipo se diseña desde ceros. Al referirse al manejo de sesiones de usuario suele pensarse únicamente en el proceso de capturar el nombre de usuario ( username ) y su cont
Publicar un comentario
Leer más

Manejo de clases globales únicas en PHP

Imagen de Tumisu en Pixabay ¿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 de
Publicar un comentario
Leer más

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

Imagen de garionhk en Pixabay 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
Publicar un comentario
Leer más