ZonaPHP

Por motivos laborales, me vi en la necesidad de documentar grandes cantidades de código últimamente, un proyecto muy grande con muchos objetos ubicados en distintos directorios. Además, sumado al hecho de que es muy probable que se agreguen más programadores, la necesidad de tener una documentación del código ya no era por el mero hecho de la mala memoria propia, sino que se tornaba realmente necesario para que puedan ponerse al día rápidamente.

Así que buscando en Google, caí rápidamente en dos proyectos, creados en PHP, para generar documentación en base al código. Uno llamado PHPDocumentor y el otro PHPDoc (el que diga que los programadores no tienen imaginación a la hora de poner nombres, que sepa que se equivoca). El primero, parece que se erigió como el standar en la generación de documentación, mientras que el segundo, era una opción interesante a la hora de encontrar un reemplazo. Lo que no esperaba era encontrarme con un leve problema: Ninguno de los dos funcionó en mi máquina de desarrollo, ni bien instalados. Muy extraño, porque recuerdo haberlos utilizado en el pasado, pero esta vez, no hubo caso. Les edité el código fuente, cambié extensiones y constantes. Nada.

Así es como caí en las dos soluciones que estoy utilizando actualmente y con las cuales, tengo resuelto el tema de la documentación en el mediano plazo. El primero de ellos, es un proyecto llamado Doxygen, muy conocido en el ámbito de Java y C++, pero que me sorprendió gratamente al ver que también funcionaba con PHP. Mucha gente lo utiliza (por ejemplo, la gente de KDE) y ya veo por qué: crea la documentación separada en lista y jerarquía de clases, por archivos, módulos o estructuras de datos. Además ofrece la posibilidad de generar archivos HTML, CHM, RTF, PDF, LaTeX, PostScript o man pages.

PHPXref.com

Esto parecería ser suficiente, si no fuera porque encontré otro generador, llamado PHPxRef, con una característica muy interesante: linkea toda llamada de un método, función, variable o constante, hacia el lugar del código donde está definido (aunque sea en otro archivo). Complementa a la perfección a Doxygen y como éste, son aplicaciones que se instalan en la PC (si usan windows, aunque también están disponibles para linux) y pueden utilizarse sin problemas, y sin tener PHP instalado. Si quieren ver un ejemplo de PHPxRef, pueden acceder a PHPxRef.com, donde hay una lista de documentación generada de algunas aplicaciones Open Source conocidas.

¿Pero como se documenta el código?

Esto merecería ser parte de un artículo aparte, lo cuál esto no pretende ser, pero básicamente, un standar en la documentación de código, es utilizar la sintáxis JavaDoc o PHPDoc (básicamente, lo mismo, pero con otro nombre). Si tuviéramos una clase definida en un archivo, la sintáxis PHPDoc sería:

Así, como verán, el comentario en vez de comenzar como usualmente lo hace, con /*. lo hace con un doble asterisco: /**. Esta sutil diferencia, permite que un programa pueda leer los comentarios cercanos a las declaraciones de clases o métodos, y agregar el contenido a la documentación. Así como ven palabras clave especiales (@uses, @author, @version, @package, etc), hay muchas otras para indicar, por ejemplo, los tipos de parámetros que recibe una función (@param) o el valor que la misma devuelve (@return). Para los más curiosos, les dejo una explicación sobre Como documentar código.

Aunque parezca que el sitio está abandonado hace mucho tiempo, y que sigue online solo porque alguien se olvidó de borrar el directorio, la realidad dista mucho de ello. Luego de la mudanza de zonaPHP al formato blog (específicamente, a WordPress), también hemos cambiado la versión de este soft por la última disponible.

Sabemos, en el fondo, que eso no es todo. Pero por suerte estamos trabajando para que todo esto cambie. Muy pronto (y muy pronto en serio) estaremos dando un paso primordial para mantener a la comunidad de usuarios de PHP que se registran día a día en el sitio, estrenando un foro de discusiones para que podamos estar aún más en contacto, no solo con los comentarios de los artículos.

Para esto, hemos trabajado con bbPress, un soft de foros aún muy en desarrollo, pero que se integra fantásticamente con WordPress y su base de usuarios. De esta manera, no será necesario registrarse nuevamente al foro, y la experiencia de uso será muy sencilla, ya que el diseño estará integrado de igual manera. Nos quedan solo unos detalles estéticos, y ya marcaremos la fecha del lanzamiento.

Hasta ese momento, un saludo muy grande a todos los usuarios de PHP.