Hackeando phpDocumentor

Uno de mis objetivos en torno al desarrollo web en general, es respetar lo más estrictamente posible los estándares W3C.

La documentación generada por phpDocumentor lamentablemente no es completamente limpia en ese sentido. Y como phpDocumentor es Software Libre, decidí meterle mano.

phpDocumentor tiene unas clases “Converter”, dedicadas a transformar la información analisada del código fuente en el formato de salida. Los 2 converters afectados son HTMLframesConverter.inc y HTMLSmartyConverter.inc.

frames hace la documentación en páginas HTML en marcos, y Smarty en una página completa por cada elemento documentado. Ambos usan smarty como motor de plantillas.

Fijándome en los errores descubiertos por Html Validator for Firefox y ZendStudio, logré identificar los archivos fuente afectados. En su mayoría eran errores tontos en las plantillas, como el uso de mayúsculas en las etiquetas y nombres de atributos, falta de atributos obligatorios y esas cosas. Pero hay unos detalles que no depende de los templates, sino de las clases Converter. Por ejemplo, me topé con que el árbol de clases queda con etiquetas de cierre </ul> y </li> sueltas. Tampoco se escapan los caracteres “&” de los parámetros pasados por referencia. Muchos otros lugares de las plantillas tienen problemas con etiquetas con contenido vacío (por ejemplo, me vi obligado a rellenar el tag @copyright en todos los archivos fuente y así evitar un <ul></ul>).

Ojeando el código, encontré que el método getRootTree() consiste en un algoritmo iterativo que recorre el arreglo de nodos de información de las clases. El problema es que los método iterativos que trabajan con arreglos o árboles, suelen requerir muchas más variables auxiliares, por lo cual confunde mucho. Además recuerdo haber trabajado en una clase que desplegaba listas HTML con <ul> y <li>, pero usando un método recursivo.

Para quien le interese el concepto, hay un patrón de diseño llamado “Composite”, que ocupa el mismo principio de recursividad, pero en el recorrido se hace entre objetos (cada nodo es propiedad de otro objeto de igual clase).

Como me fue imposible comprender el error, decidí derechamente reescribir el método del HTMLframesConverter.inc y HTMLSmartyConverter.inc (era idéntico). Además, tuve que quitar unas etiquetas de apertura<ul> y cierre </ul> en los métodos generateFormattedClassTrees() y generateFormattedInterfacesTrees() que invocaban a getRootTree().

Acá está uno de los archivos fuente modificados por mí, por si alguien le interesa: http://pastebin.com/f3c61b7c5

Por supuesto, mandé este tema al bug tracker y a la lista de correos de phpdocumentor. Espero que ojala se resuelvan los detalles pendientes. Por lo que he visto, últimamente están más concentrados en lo que será el soporte de PHP6.

Mezcla de consejos para codear, versionar y documentar.

Hoy encontré la respuesta a una duda bastante específica. Cada vez que revisaba un archivo fuente de Zend Framework, PHPDocumentor o cualquier otro proyecto, veía un tag de versión (@version) en los comentarios, donde el valor era una cadena que señalaba la fecha, hora y revisión en la que se realizó el commit y el autor de este, siempre con el mismo formato. ¿Como se hacía esto automáticamente?

Haciendo una pequeña búsqueda, dí con el origen. En CVS, existía la característica de reemplazar una palabra clave del código fuente, con una propiedad del repositorio/copia-de-trabajo. SVN heredó la misma característica. Se le llama “propiedades”.

Es extremadamente útil contar con la información del Id, revisión, fecha y autor del archivo fuente, debido a que hay muchas situaciones fortuitas en las que es crítico encontrar uno o varios archivos fuente afectados por algo.

Por ejemplo, si encuentro un bug, puedo reportar que archivo y versión está afectado.

Si un tercero realiza una implementación en algún archivo fuente, que requiere una función especial, puede documentar su código, incluyendo desde y hasta que versión es compatible su código con el de la rama principal.

Esta y otras cosas más, que he aprendido en el camino, son aquellas que me gustan tener a mano y compartir, así que ¡manos a la obra!

Seguir leyendo Mezcla de consejos para codear, versionar y documentar.

OK, cambié de opinión. Me quedo con jQuery

Por las siguientes razones:

  • Cumple con lo que promete: “Write less, do more” (Escribe menos, hace más)
  • Es más ligera que Mootools, Dojo y otras…
  • No obliga a ensuciar el HTML.
  • Licencia Dual, ambas libres:
    Dual licensed under the MIT (MIT-LICENSE.txt)
    and GPL (GPL-LICENSE.txt) licenses.
  • Respaldo: Acualmente la usan Google, Dell, Mozilla, y muchas otras. En su web se pueden ver en “Who’s usign jQuery?”. Si tantos “peces gordos” confían en una cosa libre, es por algo…
  • Me enteré en la semana, que tanto Microsoft (Visual Studio) como Nokia estaban interesados en incluirla en sus Kits de programación, sin hacerle cambios extraños y respetando la licencia. Fuente.
    • Si Microsoft y Nokia, empresas ligadas profundamente a su pasado “propietario”, confían tanto en un proyecto libre como para anunciar eso, es porque de verdad debe ser buena
    • No es que les tenga confianza, pero hay una ventaja: Aquellos desarrolladores acostumbrados a las herramientas de Microsoft o Nokia, podrían fácilmente entender, arreglar o cooperar con proyectos que ocupen jQuery.
  • Teniendo tanto respaldo, otros desarrolladores (yo) podemos vernos beneficiados del desarrollo de lo los “peces gordos”, sean de usuarios de Microsoft, Nokia, independientes, …
  • Razón trivial: Encontré otro ejemplo de DatePicker (pinchar una fecha en un calendario y seleccionar ese dato en un formulario), más bonito, completo y útil que el que estaba usando con Mootools.
    • Examinando este plugin, y la biblioteca de Plugins de jQuery, me parece suficiente para considerarla poderosa.

Así que ahora procederé a añadir jQuery al repositorio de Gonium, y aplicaré los mismos objetivos que en el post pasado, es decir, organizar los archivos, clases, etc…