Se encuentra en:
Documentar en Drupal
LIBP-0126 (Libro de pautas)
- Área: Codificación y construcción en Drupal
- Tipo de pauta: Directriz
- Carácter de la pauta: Obligatoria
A continuación se van a ofrecer una serie de recomendaciones para documentar el código para desarrollar en Drupal. Se siguen la mayoría de las convenciones de estilo seguidas por Doxygen. A continuación vamos a ofrecer una serie de recomendaciones para documentar en Drupal.
Pautas
| Título | Carácter |
|---|---|
| Documentar una función | Obligatoria |
| Documentar las constantes | Obligatoria |
| Documentar módulos | Obligatoria |
Documentar una función
Cuando se documenta una función, la documentación del bloque debe de ir situado justo encima de la función que se documenta y sin que existan líneas en blanco. Drupal interpreta la mayoría de las anotaciones constructoras utilizados por Doxygen. un bloque de documentación tiene la siguiente estructura:
/**
* Añade botones pro defecto aun formulario.
*
* @ingroup forms
* @see system_settings_form_submit()
* @param $form
* un array asociativo que contiene la estructura del formulario.
* @return
* La estructura del formulario.
*/
function system_settings_form($form) {
...
}
Lo mejor de adherirse a estas normas es que puede generar automáticamente documentación de los módulos usando la API contributed module. El módulo API es un aplicación de un subconjunto de la especificación del generador documentación Doxygen, sintonizado para producir una salida que mejor beneficia a una aplicación en base a código de Drupal.
Documentar las constantes
Las constantes deberían de ser en letras mayúsculas, su nombre completo , con separadores de guiones bajos entre la diferenciación de palabras. Es buena practica explicar para que va a ser usada la constante
/**
* Identificador de rol para usuarios autenticados.Debe de coincidir con algún valor de la tabla de roles.
*/
define('DRUPAL_AUTHENTICATED_RID', 2);
Documentar módulos
Previamente a declarar las funciones es recomendable definir de forma breve que es lo que realiza el modulo, para ello utilizar el siguiente formato:
/**
* @file
* Describir brevemente la funcionalidad que es cubierta por el módulo.
*
* Un párrafo o dos que definan a grandes rasgos sobre su módulo y cómo se comporta
*/
