Difference between revisions of "Cómo documentar un Proyecto en PHP con NetBeans"
Jump to navigation
Jump to search
(16 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
==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. <source lang="bash">sudo ln -s /usr/local/apigen/apigen.phar /usr/local/bin/apigen</source> | |||
== Configuración Netbeans == | == Configuración Netbeans == | ||
'''Nota''': Esta forma no aplica con ApiGen 4+. | |||
Ingresar a la pestaña Profile -> Options. | Ingresar a la pestaña Profile -> Options. | ||
==== ApiGen ==== | ==== ApiGen ==== | ||
Line 9: | Line 16: | ||
- ApiGen Script: '''/usr/local/netbeans-7.3/apigen/apigen.php''' | - ApiGen Script: '''/usr/local/netbeans-7.3/apigen/apigen.php''' | ||
== | ==Cómo Documentar== | ||
Line 16: | Line 23: | ||
#En la línea anterior de cada clase escribir /**. | #En la línea anterior de cada clase escribir /**. | ||
#En la siguiente línea poner * una breve descripción de la clase | #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 */. | #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. | |||
<syntaxhighlight lang="php"> | |||
/** | |||
* 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; | |||
} | |||
</syntaxhighlight> | |||
=== Para las Funciones === | === Para las Funciones === | ||
En la línea anterior de cada función escribir /** y presionar la tecla enter | #En la línea anterior de cada función escribir /** y presionar la tecla enter. | ||
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. | #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. | |||
<syntaxhighlight lang="php"> | |||
/** | |||
* 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); | |||
} | |||
</syntaxhighlight> | |||
=== Importante === | === Importante === | ||
El formato de la documentación de cada función empieza con /** | #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: | |||
<source lang="bash"> | |||
apigen generate --source [directorio a documentar] --destination [directorio de destino] | |||
</source> |
Latest revision as of 15:40, 2 June 2015
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]