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.
Comentarios
Publicar un comentario