David Esperalta

Para generar la documentación a partir del código fuente de Gesbit, vengo utilizando el programa phpDocumentor, y no es que me vaya mal del todo, aunque, esta aplicación puede llegar a dar un poco de miedo, porque, y no exagero, generar la documentación de Gesbit viene a costar unos veinte minutos, y un consumo de la CPU extraordinario, con lo que viejo PC las pasa canutas.

Como tengo la sana costumbre de pasar por SourceForge de vez en cuando, a veces me topo con pequeñas joyas, como creo que es el programa que me he encontrado esta tarde: phpDoctor. Ahora bien, hasta el diamante más brillante ha de tener algún fallo, ¿no? Y en el caso de phpDoctor hemos de tener en cuenta que no tiene todas las funcionalidades que ofrece phpDocumentor, y, sin embargo, no deja de ser un excelente programa, en mi opinión.

El caso es que los veinte minutos que tardo en generar la documentación de Gesbit usando phpDocumentor, se queda en cuestión de segundos utilizando phpDoctor. ¿He dicho segundos? Así es. Rara vez, en las pruebas que he llevado a cabo, ha pasado del minuto en generar la documentación del proyecto. Además phpDoctor cuenta con muy completa documentación, y, si antes he dicho que era más sencillo que phpDocumentor, también he dicho que no tanto.

Una de las características que pueden echarse en falta en phpDoctor es que, hasta donde yo he podido llegar, no incluye el código fuente del proyecto en la documentación. Esto es una opción en phpDocumentor, que, parece no estar disponible en phpDoctor. Y seguro de que esta es una tarea que le lleva su tiempo a phpDocumentor. Sólo por esto he dudado en usar phpDoctor en lugar de phpDocumentor, pero, lo cierto es que se muestra muy, muy rápido.

Si no conocías el programa phpDoctor, échale un vistazo. No pierdes nada.

En Gesbit estoy documentando el código fuente utilizando las convenciones de "Java", de modo que luego el programa phpDocumentor pueda "parsear" el código fuente y ofrecer su documentación en diferentes formatos además.

Sin embargo, la "interfaz web" que proporciona este último programa no termina de convencerme, y, además, la última versión del programa no parece ir muy bien con PHP 5, de modo que tenía que estar "cambiando" entre diferentes versiones de PHP.

Pero, entonces llegó phpWinDoc. Este programa para Windows, como su nombre indica, utiliza su propia instalación de PHP, que incluye, y su funcionamiento se me hace más sencillo que la interfaz web de phpDocumentor.

Configuras una vez y ejecutas las que quieras. Te evitas tener que estar cambiando de versión de PHP, si es que, como en mi caso, necesitas PHP 5. En definitiva, un programa "freeware", gratuito, que está bastante bien y que cumple con su cometido.

Una vez configurado basta con un "clic" para que te genere la documentación de tu proyecto. Si no lo has probado y usas phpDocumentor para tus proyectos PHP, échale un vistazo a phpWinDoc, porque puede que, como a mí, te resulte la mar de útil.

Así es, amigos. Desde que hace un par de días publicase en los foros del ClubDelphi un enlace para descargar la primera versión pública de Gesbit, digo, he hecho algunos cambios, y, bueno, por fin la presento también aquí, para todos aquellos interesados.

Conste que no es una versión que recomiende utilizar "en producción", por la sencilla razón de que no garantizo compatibilidad con nuevas versiones. Pero ya podéis echar un vistazo, por ejemplo, en Windows, usando "localhost", si lo veis oportuno.

En fin. No diré que comentéis lo que os parece, porque, lo diga o no lo diga vais a hacer lo que os salga de ahí mismo, y me parece bien, qué coño. Para descargar la versión 0.5 Hummingbird (colibrí) de Gesbit podéis seguir este enlace: Descarga Gesbit

Por favor, sed clementes. Y otra cosa. Esta distribución de Gesbit ocupa un poco más de la cuenta, se trata de una distribución un tanto especial, porque, incluye la documentación de Gesbit (generada por phpDocumentor) y algunos plugins que, probablemente, no se distribuirán junto con el código "base" en un futuro.

Quién no conoce phpDocumentor. Desde luego quien haya visto código PHP probablemente se topase con comentarios preparados para ser procesados por PHPDocumentor. Efectivamente, sirve para documentar código fuente, siguiendo el mismo juego de etiquetas que JavaDoc, si no estoy equivocado.

Yo procuro utilizarlo, y, sobre todo, si quieres que alguien colabore con tu proyecto, una buena forma de empezar es documentando el código completamente. Y haciéndolo con phpDocumentor consigues que acto seguido el código fuente pueda procesarse de modo que sus comentarios y documentación se presenta bien formateado en forma de manual HTML, CHM y otros formatos.

Sin embargo phpDocumentor no es sencillo de usar. Quiero decir, utilizar ciertas etiquetas, acaso las más importantes, no es complicado, al contrario, es bastante sencillo, pero, como es habitual en este tipo de herramientas para programadores, sacar partido a todo lo que el programa puede dar de sí... eso es otro cantar.

Yo por lo menos he pasado más de una vez y más de dos por el manual de phpDocumentor, y aún no me queda claro cómo utilizarlo de forma efectiva, cuando menos correcta. Sin embargo, como digo, aunque sólo sea con las etiquetas básicas, aquellas que indican el tipo de los parámetros de un método o su resultado... para esto no usar algo como phpDocumentor no tiene sentido.

Quiero decir que de alguna manera hay que dejar claro qué tipo de parámetros recibe un método, por ejemplo, y, aunque pueda hacerse con simples comentarios... ¿por qué no usar los comentarios que phpDocumentor reconoce? De este modo nos aseguramos que quien quiera adentrarse en los vericuetos de nuestro código fuente pueda hacerlo empezando por un manual HTML que le anime a hacerlo.

Una de las cosas que me gustaron del lenguaje C# el tiempo en que me interesó fue el que incorporara "de serie" un sistema de documentación mediante comentarios, esta vez formateados mediante etiquetas XML. Delphi no incorpora aún algo así... que yo sepa. Aunque existen soluciones como PasDoc, similar, pero no tan terminado como phpDocumentor.