Otro Blog Más

Una de las partes importantes de un proyecto es la documentación, y me refiero a la documentación técnica y no a los manuales de usuario. De cara a nuevos proyectos, al principio se puede plantear la opción de utilizar PHPDocumentor para hacer la documentación de los ficheros de una manera estándar, y con la potencia que da para http://es.wikipedia.org/wiki/PhpDocumentor de la aplicación. Todo y eso, sigue habiendo el problema que la acción de documentar es muy tedioso para los desarrolladores y nunca apetece dedicar tiempo.

Su pueden configurar los proyectos que estén en un Subversion, para que en cada commit, el repositorio modifique valores dentro de las cabeceras de PHPDocumentor que hay en el código de los ficheros modificados. Esto solamente funciona en archivos PHP (con extensiones como .php o .phtml), y requieren tener una cabecera similar a la siguiente:

/**
 *
 * @author     $Author$
 * @category
 * @package
 * @subpackage
 * @version    $Id$
 * @since      0
 */
 
/**
 *
 * @author     $Author$
 * @category   
 * @package    
 * @subpackage 
 * @version    $Rev$
 * @since      0
 */

Estos ficheros hay que añadirles una propiedad de Subversion: svn-keywords. El valor que necesita esta propiedad es:

Author Date Rev Id

Así, Subversion buscará los campos de la cabecera que puede rellenar, y introducirá los valores que pertoquen, según el commit. En las siguientes modificaciones, irá actualizando los valores si es que se han realizado cambios en el fichero.

Entradas relacionadas:

1. Guía para crear documentación con PHPDocumentor
2. Configurar Subversion para utilizar los repositorios externos de Zend Framework
3. Configurar XAMPP para debugar con XDebug en Netbeans
4. Subversion: reutilizar branches ya reintegrada sin tener conflictos
5. Configurar PHP para que muestre los errores