LesOlivex

Servicios informáticos



Generar documentacion externa con doxygen

Category : Documentación de código, doxygen, Programación dic 21st, 2014

Doxygen ademas de documentar el código, nos permite una manera de crear documentación extra en archivos separados del código.

En caso de documentar para php añadir simbolos de comentarios para que doxygen los recoga.

Al inicio del archivo /** y al final */

Ejemplo:

Generamos archivos readme.dox para generar un manual de la aplicación.

@page manual Manual

@section lanzadores Lanzadores al inicio

Si encontramos "$HOME/.magtrabajos/$proyecto/lanzadores" el archivo lo añadimos
al iniciar el programa. Para automatizar el lanzamiento de aplicaciones que abrimos
al trabajar en el proyecto.

Ejemplos:

@code 
# Si hay sesión de vim anterior la abrimos y la borramos 
[[ -e Session.vim ]] && ( gvim -S Session.vim ; sleep 2s ; rm -f Session.vim )

# Lanzamos firefox con pagina del proyecto en local
$mt_navegador $mt_web_local &
@endcode

- @subpage plugins "Plugins"
- @subpage complementos "Complementos"

plugins/readme.dox

@page plugins Plugins

Para extender la aplicación.

Para que un plugin este activado debe estar en la lista de @see mt_plugins_activados, dentro 
de la configuración del proyecto.

@section estructura_plugins Estructura del directorio

<pre>
magsubversion/
|-- eventos
|   |-- pre_cerrar_movimiento
|   |   `-- 20-subversion.sh
|   `-- pre_cerrar_tarea
|       `-- 10-subversion.sh
|-- extension.sh
|-- magsubversion
`-- menu.sh
</pre>

@section eventos Eventos

Al ejecutarse un evento se buscara dentro de la carpeta de cada plugin si contiene un script para ser ejecutado
se tendrá en cuenta el orden según el nombre del script

@section extensiones Extensiones 

El archivo extension.sh es una porción de código que sera incluido dentro de la aplicación principal al ser lanzada.

@section menu_plugins Menú para los plugins

El archivo menu.sh si se encuentra se mostrará en la lista de componentes para ser lanzado si se selecciona.

 

Documentar scripts bash con doxygen

Category : bash, Documentación de código, doxygen dic 21st, 2014

doxygen_manualDoxygen tiene la capacidad de hacer un filtrado antes de procesar los archivos, para activarlo creamos un script en bash que debe contener lo siguiente:

cat "$1" | sed 's/##</\/\/\/</g' | sed 's/##/\/\/\//g' | sed '/\/\/\/\|^$/!s/$/;/'

En la configuración de doxygen añadimos los siguientes cambios:

INPUT_FILTER           = "../../proyectos/mytrabajos/magdoxygen --filtra bash"
FILTER_SOURCE_FILES    = NO

Modificar el script que yo puse por el vuestro

A la hora de documentar el código marco con dos ‘##’ los comentarios para doxygen, en caso de hacerlo posteriormente ‘##<‘ el script los transformara en /// y ///< para que doxygen los entienda.

Y eso es todo.

Doxygen, conceptos básicos

Category : Documentación de código, doxygen dic 21st, 2014

Documentación de código

Para que doxygen tenga en cuenta los comentarios deben tener el siguiente formato:

  • /** Comienza bloque comentado
  • */ Termina bloque
  • /// comentario de una linea
  • ///< Despues del elemento

Etiquetas generales:

Las etiquetas iran precedidas de ‘@’ o ‘\’

  • file
  • todo
  • author
  • param
  • return
  • version
  • see
  • tables para indicar las tablas que se utilizan de mysql
  • deprecated
  • brief
  • bug
  • code
  • example

Etiquetas de formato:

  • c fuente en monospace para la siguiente palabra
  • b negrita
  • e itálica

Paginas extras:

Se generan paginas sobre las etiquetas:
  • todo:  Tareas pendientes
  • bug: Lista de errores
  • example: Código de ejemplo
  • deprecated: Código en desuso

Ejemplos

Encabezado de fichero:

/**
 * @file
 *
 * @author    Eduardo Magrané
 *
 * @internal
 *   Created  24/11/09
 *  Revision  SVN $Id: $
 * Copyright  Copyright (c) 2009, Eduardo Magrané
 *
 * This source code is released for free distribution under the terms of the
 * GNU General Public License as published by the Free Software Foundation.
 */

Encabezado de clase:

/** Módulo Eventos
 *
 * Utilizamos los eventos como manera de interconectar a los módulos
 * Ejemplo de fichero de eventos de un módulo.
 *
 * @see modulos/editar/eventos_usuario.php
 *
 * @code
 * <?php
 *    $eventos['cabecerad']['formulario_busqueda'][1]='';
 *    $eventos['columna']['ultimas_entradas'][2]="num=7&seccion=".Router::$s."&formato=1";
 *    $eventos['contenido_dinamico']['contenido_dinamico'][1]='';
 *    $eventos['precarga']['presentar_busquedas'][3]='';
 *
 *    // Comportamiento de eventos
 *    $cEventos['contenido_dinamico'] = 'unico';
 * ?>
 * @endcode
 *
 * @author Eduardo Magrané
 *
 * @todo Cachear array de eventos
 */

Campos de datos:

/**
 * Array con los eventos de la aplicación
 */

public $eventos;

Metodo:

/**
 * Buscamos dentro de modulos los archivos directorio módulo/eventos_usuario.php
 * que tienen la información del módulo.
 */

function leer_eventos($nivel) {

Test:

Se generara una página nueva dentro de “Páginas relacionadas” con el nombre “Lista de pruebas”

/**
 * @test Comprobando GcmConfigFactory
 */

class GcmConfigFactoryTest extends PHPUnit_Framework_TestCase{

   /**
    * @test Comprobando valor de la primera variable
    */

   function testCambiarValores() {

      $this->assertEquals($this->config->get('v1'), 'variable1');

      }

   }

Agrupación con doxygen

Category : Documentación de código, doxygen dic 21st, 2014

Añadir un grupo nuevo:

## @defgroup libash Librerías para bash
## @{
.....
## @}

Todo el código entre las llaves sera mostrado dentro de la sección de módulos

Tambíen podemos añadir a un grupo existente:

## @file configuracion
##
## @brief Librería para gestionar la configuración de los scripts de bash
##
## Para trabajar con esta librería es necesario que tengamos un archivo de configuración definido,
## y sus variables deben tener un prefijo que las identifique.
##
## @ingroup libash

El archivo configuración sera referenciado dentro del módulo de libash