Voilà, voilà... Fin de l'aventure...

 

Fermeture de kolossaldrupal.org dans...


Bonjour tout le monde,

Drupal évolue, les versions changent et Kolossaldrupal.org était essentiellement consacré à la version 6 de Drupal.

Autant dire que les infos présentées ici commencent à dater...

Faute de temps, je ne peux plus garder le site Kolossaldrupal à jour...

Je vous aurais bien proposé de reprendre le flambeau mais... c'est tellement simple de nos jours de se faire son propre site à soi...Pourquoi s'embêter alors ? :-)

Ce site restera donc en l'état, tel qu'il était en 2011...

Ah la la ! Cela ne nous rajeunit pas !

Manuel Vila - Avril 2016

Conventions de formatage Doxygen

Conventions de formatage Doxygen

Référence sur drupal.org : 28 Mai 2009 – 14h16 - http://drupal.org/node/1354


Doxygen est un logiciel permettant de créer une documentation. Les informations sont directement puisées dans le code-source, ce qui en rend la maintenance plus aisée et plus conforme avec le code-source.

Le site Doxygen fournit un excellent manuel de l’utilisateur. Les notes qui suivent concernent l’implémentation de Doxygen dans Drupal.

Syntaxe générale pour la documentation

Pour documenter un bloc de code, la syntaxe à utiliser est la suivante :

 * Documentation here.
 */

Doxygen analysera tout commentaire placé dans ce type de bloc. Notre but est d’utiliser le moins de commandes Doxygen possibles, pour préserver la lisibilité du code. Toute mention de fonctions ou de fichiers dans la documentation sera automatiquement liée au code correspondant, il sera donc inutile de présenter les balises qui génèrent les liens.

Documenter les fichiers

Il est recommandé de de décrire, en début de chaque fichier, ce qu’il fait. Par exemple :

<?php
// $Id: theme.inc,v 1.202 2004/07/08 16:08:21 dries Exp $

/**
* @file
* The theme system, which controls the output of Drupal.
*
* The theme system allows for nearly all output of the Drupal system to be
* customized by user themes.
*/

La ligne se trouvant juste après la directive @file est une brève description qui sera affichée dans la liste des fichiers de la documentation. Si la ligne commence par un verbe, il devra être au présent (par exemple : « Handles files uploads »). Une description plus détaillée peut se trouver après une ligne vierge.

Pour ajouter à votre fichier la balise ID du CVS, ajoutez un // $Id$ à votre fichier. CVS le complétera automatiquement au format indiqué précédemment. Dans le futur, vous n’aurez plus à vous en préoccuper car CVS actualisera automatiquement cette information.

Pour les fichiers .install, le modèle suivant est utilisé :

/**
 * @file
 * Install, update and uninstall functions for the XXX module.
 */

Documenter les fonctions

Toutes les fonctions susceptibles d’être appelées par d’autres fichiers devraient être documentées; les fonctions privées peuvent également être documentées. Un bloc de documentation de fonction devrait immédiatement précéder la déclaration de fonction elle-même, comme ceci :

/**
 * Verify the syntax of the given e-mail address.
 *
 * Empty e-mail addresses are allowed. See RFC 2822 for details.
 *
 * @param $mail
 *   A string containing an email address.
 * @return
 *   TRUE if the address is in a valid format.
 */
function valid_email_address($mail) {

La première ligne du bloc devrait contenir une brève description de ce que fait la fonction, elle débutera par un verbe sous la forme « Do such and such » (plutôt que « Does such and such »). Une description plus longue, comprenant des indications d’utilisation peut être ajoutée, en laissant une ligne vierge avant.

Les paramètres seront mentionnés avec la directive @param, avec leur description dans la ligne d’après. Après tous les paramètres, une directive @return doit être utilisée pour indiquer la valeur retournée par la fonction, si elle existe. Il n’y a pas de ligne vierge entre les directive @param et @return.

Les fonctions qui peuvent être décrites en une seule ligne peuvent omettre ces directives, comme ci-dessous :

/**
 * Convert an associative array to an anonymous object.
 */
function array2object($array) {

Les paramètres et la valeur de retour doivent être décrits dans cette seule ligne de description.

Documenter l’implémentation des hooks

De nombreux modules sont constitués d’implémentation de hooks. Si l’implémentation est plutôt standard et n’exige pas plus d’explications que celles fournies par la référence au hook, une courte documentation peut être utilisée :

/**
 * Implement hook_help().
 */
function blog_help($section) {

Ceci génère un lien vers la référence du hook, rappelle au développeur qu’il s’agit d’une implémentation de hook, et évite d’avoir à documenter les paramètres et les valeurs de retour, qui sont les mêmes pour chaque implémentation du hook.

Documenter les formulaires

Pour fournir un guide de référence sommaire aux concepteurs de thèmes, on balise chacune des fonction qui construisent les formulaires, ainsi Doxygen peut les regrouper ensemble.

Une fonction de construction de formulaire est une fonction pouvant être utilisée comme argument pour drupal_get_form. Pour ce faire, ajoutez une instruction de regroupement à la documentation de cette fonction. De plus, alors que submit, validate et autre gestionnaires du formulaire ne sont pas destinés à figurer dans le groupe, vous devrez fournir un @see pour fournir une référence aux gestionnaires rattachés à ce formulaire.

/**
 * FAPI definition for the user login form.
 *
 * ...
 * @ingroup forms
 * @see user_login_default_validators()
 * @see user_login_submit()
 */
function user_login(&$form_state, $msg = '')

Documenter les fonctions de thèmes

Pour fournir un guide de référence sommaire aux développeurs de thèmes, on balise toutes les fonctions « thémables » pour que Doxygen puisse les regrouper sur une seule page. Pour ce faire, ajoutez une instruction de regroupement à la documentation de ces fonctions :

/**
 * Format a query pager.
 *
 * ...
 * @ingroup themeable
 */
function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = array()) {
  ...
}

Documenter les gabarits de thème

Si une gabarit et une fonction de pré-traitement est utilisé à la place d’une fonction de thème, une déclaration de fonction vide pour la fonction de thèe qui n’est pas utilisée doit être placée dans la documentation contributive (contributions/docs/developer/theme.php).

Le gabarit lui-même doit être documentée avec la directive @file et doit contenir la liste des variables que template_preprocess_HOOK lui a préparé.

Si l’une de ces variables contient des données dont il est, pour x raisons, risqué d’afficher la valeur, elles doivent être documentées; sinon, on suppose que les variables disponibles sont correctement filtrées. Ce qui n’est pas listé ne doit pas être considéré comme sûr pour l’affichage.

La directive @see doit également être mentionnée pour un lien vers les fonctions de pré-traitement et les fonctions theme_X

<?php
// $Id$

/**
* @file
* Default theme implementation to display a list of forums.
*
* Available variables:
* - $forums: An array of forums to display.
*
* Each $forum in $forums contains:
* - $forum->is_container: Is TRUE if the forum can contain other forums. Is
 *   FALSE if the forum can contain only topics.
 * - $forum->depth: How deep the forum is in the current hierarchy.
 * - $forum->name: The name of the forum.
 * - $forum->link: The URL to link to this forum.
 * - $forum->description: The description of this forum.
 * - $forum->new_topics: True if the forum contains unread posts.
 * - $forum->new_url: A URL to the forum's unread posts.
 * - $forum->new_text: Text for the above URL which tells how many new posts.
 * - $forum->old_topics: A count of posts that have already been read.
 * - $forum->num_posts: The total number of posts in the forum.
 * - $forum->last_reply: Text representing the last time a forum was posted
 *   or commented in.
 *
 * @see template_preprocess_forum_list()
 */

La fonction template_preprocess_HOOK doit également contenir les directives @see adéquates.

Documenter les modules contributifs et les thèmes

  • N’utilisez pas @mainpage. Il ne peut y avoir qu’un seul @mainpage dans le dépôt des contributions et il est réservé pour la page qui indexe toutes les modules tiers et les thèmes.
  • Utilisez Doxygen Modules (@defgroup, @ingroup, @addtogroup, voir « Limites et conseils ci-dessous) raisonnablement. Il y a actuellement plus de 2 200 dossiers de modules dans contrib, la plupart d’entre eux comprennent plus d’un module. Si chacun de ces modules n’utilise qu’un seul @defgroup, il y aura plus de 2 200 entrées dans la liste des Modules. Si chacun d’eux en utilise plus d’un...
  • Si vous utilisez Doxygen Modules, assurez-vous que vous ne leur donnez qu’un seule namespace, qui devrait être le nom de votre module. Par exemple : @defgroup views … pour le module Views, @defgroup views_ui … pour le module Views_UI. N’utilisez pas les noms de groupes définis dans le core de Drupal (hooks, themeable, file, batch, database, forms, form_api, format, image, validation, search, etc.).

Une façon de faire conseillée pour l’utilisation de regroupement Doxygen dans les modules tiers et les thèmes est la suivante :

Dans votre example.module principal :

/**
 * @defgroup example Example: short description of your module
 *
 * Longer description of your module, including all other files and modules.
 */
 
/**
 * @file
 *
 * Description of your module's main file.
 *
 * @ingroup example
 */

Dans les autres modules et fichiers de code de votre module :

/**
 * @file
 *
 * Description of another file in your module.
 *
 * @ingroup example
 */

De cette façon, vous avez tous les fichiers du module présentés ensemble dans le groupe  « example ».

Limites et conseils

Le module de traitement Doxygen de Drupal, api.module, ne supporte actuellement qu’un petit ensemble des commandes Doxygen et s'attend à quelque formatage du code-source. Le code à faire traiter par l’api.module doit se conformer à ces conventions.

L’api.module ne supporte actuellement que l’un des trois mécanismes de regroupement de Doxygen : Modules (@defgroup, @ingroup, @addtogroup, @{, @}). Lorsque vous les utilisez, notez ce qui suit :

  • Modules travaille à un niveau global, en créant une nouvelle page pour chaque groupe. Il ne devrait être utilisé que pour regrouper des fonction qui fournissent une sorte d’API, qui peuvent éventuellement comprendre plusieurs fichiers. A l’inverse : il ne devrait pas être utilisé pour regrouper des fonctions dans un fichier lorsque ces fonctions ne sont utilisées que dans ce même fichier. c’est le rôle de Member Groups (qui, malheureusement, n’est pas encore supporté par api.module).
  • @defgroups ne peut être déclaré qu’une fois. Déclarer un deuxième @defgroup name avec un nom déjà utilisé causera une erreur. Utilisez @defgroup dans la section la plus importante du fichier et @addtogroup / @ingroup pour l’ajout depuis d’autres endroits du fichier.
  • Le name dans @defgroup name Explaination of that group doit être un identifiant d’un mot seulement, comme l’est le nom d’une variable ou d’une fonction en PHP. Ou, en tant qu’expression rationnelle : [a-zA-Z_][a-zA-Z0-9_]*. Les points, tirets, etc, ne sont pas autorisés.

Pour voir Doxygen à l’œuvre sur la documentation du core Drupal, jetez un œil à ax' Drupal site. Plus particulièrement, regardez les « logs d’erreurs doxygen » et donnez un coup de main en améliorant la documentation du core Drupal.