Cómo documentar un Proyecto en PHP con NetBeans
Jump to navigation
Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
Instalación
Estas instrucciones aplican para ApiGen 4+.
- Descargar código de http://www.apigen.org.
- Guardarlo en un directorio, se sugiere en OS X en /usr/local/apigen.
- Volver ejecutable el archivo descargado.
- Agregar el archivo al PATH para ser usado desde cualquier parte.
sudo ln -s /usr/local/apigen/apigen.phar /usr/local/bin/apigen
Configuración Netbeans
Nota: Esta forma no aplica con ApiGen 4+.
Ingresar a la pestaña Profile -> Options.
ApiGen
- ApiGen Script: /usr/local/netbeans-7.3/apigen/apigen.php
Cómo Documentar
Para las Clases
- En la línea anterior de cada clase escribir /**.
- En la siguiente línea poner * una breve descripción de la clase
- Si es necesario una descripción mas extensa de la clase, hacer un salto de línea y escribir.
- La tercer línea terminar la documentación con un */.
- En la línea anterior a los parámetros, escribir /**.
- Se creará el parámetro, especificar tipo y describir función.
- Terminar con un */.
Ejemplo
Esto es solo una calse de ejemplo, para mostrar el formato de documentación.
/**
* Esta clase es una estructura necesaria para interactuar con ProcessMaker
*
* Descripción extensa.
*/
class variableStruct {
/** @var string nombre del parámetro. */
public $name;
/** @var string valor del parámetro. */
public $value;
}
Para las Funciones
- En la línea anterior de cada función escribir /** y presionar la tecla enter.
- Netbeans creará una lista de parámetros utilizados en la función, cada uno con el tipo y su nombre, les aparecerá algo como esto: * @param type $nombre, lo que se debe cambiar es el type, por el tipo de dato (ej:string,array,etc) y después de $nombre en la misma línea escribir que contiene este dato(ej:nombre del usuario).
- En la línea posterior a /**, escribir una breve descripción de la función.
- Si la función es demasiado larga es recomendable utilizar tag de html (ej:<ul><li>paso 1</li><li>paso 2</li></ul>) para ir describiendo paso a paso la función.
Ejemplo
Esto es solo una función de ejemplo, para mostrar el formato de documentación.
/**
* Reasigna los casos al usuario indicado.
*
* Se llevan a cabo los siguientes pasos:
* <ul>
* <li>Se obtienen los datos del caso a resignar.</li>
* <li>Se obtiene el ID del usuario a reasignar.</li>
* <li>Se reasigna el caso.</li>
* </ul>
*
* @author nombre apellido <correo>
*
* @param string APP_UID del caso.
* @param int DEL_INDEX del caso.
* @param string USR_UID del usuario ya asignado.
* @param string USR_UID del nuevo usuario a asignar.
*/
public function reasignarCaso($idCaso, $delIndex, $idOldUser, $idNewUser) {
G::LoadClass("case");
$cnn = Propel::getConnection("workflow");
$stmt = $cnn->createStatement();
$c = new Cases();
//Reasigna los casos seleccioandos a un nuevo usuario
$var = $c->reassignCase($idCaso, $delIndex, $idOldUser, $idNewUser);
}
Importante
- El formato de la documentación de cada función empieza con /**
- Cada línea de contenido debe comenzar con un *
- Finalizar la documentación con */.
Generar la documentación
Usando NetBeans
Una vez terminada la documentación de cada función y de todas las páginas php que necesita.
- Ir a la pestaña Window->Projects(Ctrl+1), donde nos listará todos los proyectos que tenemos en nuestro NetBeans.
- Hacer click derecho encima de nuestro proyecto el cuál hemos documentado y presionar en “Properties”, en la sección de “Categories” ir a “ApiGen”
- En “Target Directory” debemos indicar la carpeta en donde se generará nuestra documentación (es recomendable crear una carpeta nueva “documentación” dentro del mismo proyecto) y ok.
- Luego de hacer los pasos anteriores, volver hacer click derecho a nuestro proyecto y presionar “Generate Documentation”.
- NetBeans genera la documentación y la muestra en nuestro navegador por defecto, la url sería file:///var/www/nombre_proyecto/carpeta_documentación/index.html, aquí encontraremos la lista de todas las clases y sus funciones documentadas.
Usando Terminal para ApiGen 4+
Con NetBeans 8 o previo no se puede generar la documentación usando ApiGen 4+ ya que cambia la forma como se genera la documentación. Para generar la documentación hay que hacerlo como comando desde la línea de comando, de la siguiente manera:
apigen generate --source [directorio a documentar] --destination [directorio de destino]