Documentación

De CidesaWiki

Cada Clase, función y variable global (o de clase) debe ser documentada de la siguinete forma:

/**
 * Herramientas Varias de manejo de datos.
 *
 * @package    Siga
 * @subpackage lib
 * @author     Grupo Desarrollo Cidesa <desarrollo@cidesa.com.ve>
 * @version    SVN: $Id: $
 * @copyright  Copyright 2007, Cidesa C.A.
 * 
 */
class Herramientas
{
	/**
	 * @static 
	 * @var string $prueba Definición del comentario de una variable.
	 */
	static $prueba = 'Variable de Prueba'; 
	

	/**
	 * Función para retornar datos a partir de una sentencia sql.
	 * Esta función retorna un arreglo de registros (Arreglo Bidimencional).
	 * @todo Agregar el manejo de errores de base de datos
	 *  
	 * @static
	 * @param string $sql Instrucción SQL.
	 * @param array &$output Arreglo bidimencional de respuesta.
	 * @return bool verdadero si encontro datos.
	 */ 
	public static function BuscarDatos($sql,&$output)
    {
		$con = sfContext::getInstance()->getDatabaseConnection($connection='propel');
		$stmt = $con->createStatement();
		$rs = $stmt->executeQuery($sql, ResultSet::FETCHMODE_NUM);
		$i = pg_num_fields($rs->getResource());
		$fieldname = array();
		$result = array();
		$output = array();
		for ($j = 0; $j < $i; $j++)
			{
				$fieldname[]  = pg_field_name($rs->getResource(),$j);
			}
		while ($rs->next())
		{
			$a=0;
			while ($a < $i)
			{
				$fila = $rs->getRow();
				$result[$fieldname[$a]] = $fila[$a];
				$a++;
			}
			$output[] = $result;
		}
		if (count($rs)>0) return true; else return false;
	}
}

Se deben hacer las siguientes modificaciones:

• @subpackage: ayuda a organizar las clases o funciones dentro de grupos de librerias, por ejemplo, este codigo viene de una clase llamada Herramientas.class.php, la cual esta en la carpeta lib dentro del proyecto. Si estuviese en una carpeta mas profunda seria "lib.carpeta".

• Se debe colocar en el inicio del comentario de documentación la descripción completa de la funcionalidad de la clase.

• @todo: permite organziar las funcionalidades que estan pendiente por realizar en el clase/funcion documentada.

• Si la función/clase no es estática no debe colcoarse el tag @static.

Para major documentación de los tags que usa la herramineta PHPDocumentation pulsa aqui