Cómo documentar un Proyecto en PHP con NetBeans

From Wiki de Caballero
Revision as of 15:40, 2 June 2015 by Alex (talk | contribs) (→‎Usando Terminal para ApiGen 4+)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Instalación

Estas instrucciones aplican para ApiGen 4+.

  1. Descargar código de http://www.apigen.org.
  2. Guardarlo en un directorio, se sugiere en OS X en /usr/local/apigen.
  3. Volver ejecutable el archivo descargado.
  4. 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

  1. En la línea anterior de cada clase escribir /**.
  2. En la siguiente línea poner * una breve descripción de la clase
    1. Si es necesario una descripción mas extensa de la clase, hacer un salto de línea y escribir.
  3. La tercer línea terminar la documentación con un */.
  4. En la línea anterior a los parámetros, escribir /**.
  5. Se creará el parámetro, especificar tipo y describir función.
  6. 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

  1. En la línea anterior de cada función escribir /** y presionar la tecla enter.
  2. 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).
  3. En la línea posterior a /**, escribir una breve descripción de la función.
    1. 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

  1. El formato de la documentación de cada función empieza con /**
  2. Cada línea de contenido debe comenzar con un *
  3. 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.

  1. Ir a la pestaña Window->Projects(Ctrl+1), donde nos listará todos los proyectos que tenemos en nuestro NetBeans.
  2. 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”
  3. 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.
  4. Luego de hacer los pasos anteriores, volver hacer click derecho a nuestro proyecto y presionar “Generate Documentation”.
  5. 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]