Doxygen i format dels comentaris
Aquesta pàgina cobreix les normes per a la documentació del codi de Drupal.
Hi ha dos tipus de comentaris: en línia i les capçaleres. Els comentaris en línia són comentaris que estan dins de les funcions i del codi i que descriu els passos que es van fent, les capçaleres serveixen per definir i documentar totes les funcions, classes i mètodes i s'utilitza l'estàndard de documentació de codi anomenat Doxygen.
Podeu trobar un manual sobre doxygen a: http://www.stack.nl/~dimitri/doxygen/manual.html
1. Consideracions generals
- Tota la documentació i els comentaris han de formar frases i l'ús adequat de la gramàtica i la puntuació.
- Les frases han de ser separades per espais.
- S'utilitzen les majúscules en els comentaris per fer referència a les constants, per exemple TRUE.
- Els comentaris han de tenir una llargada màxima de 80 caràcters per línia, si es més llarg s'han d'anar afegint tantes noves línies com sigui necessari, totes elles amb un màxim de 80 caràcters i sense partir mai cap paraula.
2. Comentaris en línia
Es recomana l'ús de comentaris en línia. Els comentaris han de ser en una línia separada immediatament abans de la línia de codi o bloc que fan referència. Per exemple:
// Desselecciona totes les categories de contacte.
db_query('UPDATE {contact} SET selected = 0');Si cada línia d'una llista necessita d'un comentari per separat, els comentaris es poden fer a la mateixa línia i identar-se al mateix nivell per facilitar-ne la lectura. Per exemple:
$variable = array(
'uid' => $uid, // Identificador de l'usuari.
'locale' => 'ca', // Idioma de l'usuari.
'name' => 'Oriol', // Nom de l'usuari.
);L'estil de comentaris de C (/ * * /) i l'estàndard C++ (//) són els dos correctes, encara que el primer no es recomana dins de les funcions. L'ús de l'estil de comentaris Perl/shell (#) no es recomana. Per tant, utilitzarem principalment /* */ pels comentaris de les capçaleres, i // pels comentaris en línia.
3. Capçaleres de codi
Per a la documentació d'un bloc de codi, com per exemple un arxiu, una funció, classe, mètode, constant, etc, la sintaxi serà:
/**
* Documentació aquí a dins.
*/Per les capçaleres de blocs de codi s'utilitza l'estàndard de Doxygen. El nostre estil és utilitzar el menor nombre d'ordres específiques doxygen com sigui possible, per tal de mantenir la llegibilitat de la font. El bloc de documentació ha d'aparèixer immediatament abans de la funció, classe, mètode, etc, que està sent documentat, sense línies en blanc entre mig, i evidentment, TOTES les funciones, mètodes i classes han de tenir una capçalera de documentació explicant el que fa, quines variables espera i què retorna i com.
També és recomanable que els capçaleres incloguin exemples de com utilitzar aquella funció o mètode.
Exemple d'una capçalera que descriu una funció:
/**
* Resum aquí del que fa, si pot ser una frase en una o dues línies.
*
* @param $first
* Explicació del primer paràmetre de la funció, que és, etc.
* @param $second
* Segon paràmetre de la funció...
* @param $third
* (opcional) TRUE si s'ha de fer. Per defecte FALSE.
*
* @return
* Explicació del retorn de la funció, etc...
*/
function mymodule_foo($first, $second, $third = FALSE) {
}Exemple de llistes en la documentació:
* @param $variables
* An associative array containing:
* - tags: An array of labels for the controls in the pager:
* - first: A string to use for the first pager element.
* - last: A string to use for the last pager element.
* - element: (optional) Integer to distinguish between multiple pagers on one
* page. Defaults to 0 (zero).
* - style: Integer for the style, one of the following constants:
* - PAGER_FULL: (default) Full pager.
* - PAGER_MINI: Mini pager.
* Any further description - still belonging to the same param, but not part
* of the list.
*
* This no longer belongs to the param.3.1. Ordre i coses a documentar a les capçaleres
3.1.1. Primera línia: descripció
La primera línia del bloc ha de contenir una breu descripció del que fa la funció, i començant amb un verb en la forma "El tal" (tercera persona, com a "Aquesta funció fa tal i tal" , en lloc d'imperatiu segona persona "fer tal i tal").
3.1.2. Descripció addicional
Una descripció més detallada de notes d'ús ha de seguir després d'una línia en blanc, si hi ha més explicació que es necessita.
3.1.3. Paràmetres
Després de la descripció, cada paràmetre ha d'aparèixer amb una directiva @ param, amb una descripció sagnia de dos espais extra en la següent línia o línies. Si no hi ha paràmetres, ometeu @ param complet. No inclogui línies en blanc a la secció @ param.
3.1.4. Arguments variables
Si una funció fa servir arguments variables, utilitzeu la següent sintaxi:
* @param ...
* La descripció dels arguments de variable va aquí.3.1.5. Valor de retorn
Després de tots els paràmetres, una directiva ha de ser utilitzat per a documentar el valor de retorn si és que existeix. Hi ha d'haver una línia en blanc entre la secció @param @return.
Si no hi ha valor de retorn, ometi la directiva @return del tot.
3.2. Forma curta
Les funcions que són fàcils de descriure i d'entendre pot utilitzar-se només el resum de la funció, sense especificar res més, per exemple:
/ **
* Converteix una matriu associativa a un objecte anònim.
* /
funció mymodule_array2object ($array) {
- 3869 lectures
