Skip to research

Documentation Drupal de l'API JavaScript et normes de commentaires

Temps de lecture
Environ 4 minutes
Technologies

Le code JavaScript Drupal doit être documenté avec des en-têtes de documentation très similaires aux en-têtes de documentation PHP, avec des modifications dues à l'utilisation de l'analyseur JSDoc3 comme première étape de l'analyse du code et de la documentation. Drupal suit généralement les standards PHP autant que possible, avec les modifications suivantes :


Standards des commentaires JavaScript

  • Tous les éléments JavaScript (méthodes, constructeurs et propriétés d'objets, fonctions, variables, etc.) doivent avoir des en-têtes de documentation, sinon ils ne seront pas reconnus par l'analyseur (contrairement au module API, qui récupère tous les éléments PHP, qu'ils aient ou non en-têtes de documentation). Seuls les comportements sont documentés spécifiquement, voir l'exemple de documentation des comportements.
     
  • Tous les @tags que nous utilisons pour PHP ne sont pas pris en charge. Voir ci-dessous les balises disponibles et leur ordre de déclaration.
     
  • Pour indiquer le type de données d'une balise @param ou @return, placez le type de données entre crochets {} : @param {TheType} paramName ou @return {TheType}. Pour les données non-objet, utilisez number, string, bool, null, undefined, object, function, Array. Pour des objets particuliers, utilisez le nom du constructeur ; cela peut être une classe JavaScript intégrée (Date, RegExp), un élément DOM (HTMLElement, HTMLInputElement), une classe spécifique à Drupal (Drupal.Ajax), etc.
     
  • Balise supplémentaire : comme @throws, qui documente les exceptions lancées par une fonction PHP ou JavaScript, utilisez @fires pour documenter les événements déclenchés par une fonction JavaScript. De plus, si l'événement est un événement personnalisé (par opposition à un événement standard comme une pression sur une touche), ajoutez un bloc de documentation juste avant la première ligne de code dans une fonction qui déclenche l'événement, avec une balise @event, pour documenter l'événement lui-même (voir l'exemple ci-dessous pour plus de détails). N'incluez qu'un seul bloc @event pour chaque événement personnalisé, mais utilisez @fires dans chaque fonction qui déclenche l'événement personnalisé.
     
  • Balise supplémentaire : lors de la documentation d'un objet qui n'est pas utilisé comme espace de noms ou classe, utilisez les balises de nom @prop {type} pour documenter ses propriétés (celles-ci fonctionnent comme @param pour les paramètres de fonction).
     
  • Une notation supplémentaire est requise dans de nombreux cas pour aider JSDoc à déterminer quel type d'élément est documenté.
    • Utilisez @name pour indiquer à JSDoc le nom de ce qui est documenté, s'il n'est pas le même que le nom dans le code (généralement parce qu'il s'agit d'un nom de fonction comme DropButton plutôt que d'inclure le nom de classe comme Drupal.DropButton).
       
    • Utilisez @constructor pour indiquer qu'une fonction est destinée à être un constructeur de classe.
       
    • Utilisez @namespace pour indiquer qu'un objet est destiné à être un espace de noms.
       
    • Vous n'avez pas besoin d'utiliser @function dans la plupart des cas - JSDoc supposera que tout ce qui est déclaré en tant que fonction est une fonction ou une méthode normale, à moins que l'une des balises ci-dessus ne remplace cette détermination.

 

Ordre des balises

Les balises disponibles doivent être déclarées dans l'ordre suivant :

/**
 * 
 * @global
 *
 * @typedef
 * @var
 * @name
 * @namespace
 * @constructor
 * @callback
 * @event
 * @function
 * 
 * @augments
 * @lends

 * @type
 * @prop

 * @param
 * @return

 * @throws
 * @fires
 * @listens

 * @ingroup
 * @deprecated
 * @see
 * @todo
 * @ignore
 * 
 */

 

Documenter un fichier JavaScript

/**
 * @file 
 * Provides some feature.
 *
 * The extra line between the end of the @file docblock
 * and the file-closure is important.
 */
    
(function ($) {

  "use strict";

})();

 

 Documenter les comportements

/**
 * Attaches the table drag behavior to tables.
 *
 * @type {Drupal~behavior}
 * 
 * @prop {Drupal~behaviorAttach} attach
 *   Specific description of this attach function goes here.
 * @prop {Drupal~behaviorDetach} detach
 *   Specific description of this detach function goes here.
 */
Drupal.behaviors.tableDrag = {
  attach: function (context, settings) {
    // ...
  },
  detach: function (context, settings, trigger) {
    // …
  }
};

 

Documenter les constructions habituelles

/**
 * Holds JavaScript settings and other information for Drupal.
 *
 * @namespace
 */
var Drupal = {
   // ...
  /**
   * Holds behaviors for Drupal.
   *
   * @namespace
   */
  'behaviors': {},
  // ...
};

/**
 * Returns the value of foo for the current widget.
 *
 * Description of this ordinary function in the Drupal namespace goes here.
 *
 * @return
 *   The value of foo in the current widget.
 */
Drupal.getCurrentFoo = function () {
  // ...
};

/**
 * Constructs a table drag object.
 * 
 * Provides the ability to drag to manipulate a table and its fields.
 * 
 * @constructor
 *
 * @param {HTMLTableElement} table
 *   DOM object for the table to be made draggable.
 * @param {object} tableSettings
 *   Settings for the table.
 */
Drupal.tableDrag = function (table, tableSettings) {
  // ...
}

/**
 * Hides the columns containing weight and parent form elements.
 *
 * @fires event:columnschange
 *
 * @see Drupal.tableDrag.showColumns
 */
Drupal.tableDrag.prototype.hideColumns = function() {
  // ...

  /**
   * Indicates that columns have changed in a table.
   *
   * @param {string} type
   *   Type of change: 'show' or 'hide'.
   *
   * @event columnschange
   */

  $('table.tableDrag-processed').trigger('columnschange', 'hide');
  // ...
};

/**
 * Shows the columns containing weight and parent form elements.
 *
 * @fires columnschange
 * 
 * @see Drupal.tableDrag.hideColumns
 */
Drupal.tableDrag.prototype.showColumns = function() {
  // This event is documented in Drupal.tableDrag.hideColumns
  $('table.tabledrag-processed').trigger('columnschange', 'hide');
};

 

Traduction de l'article JavaScript API documentation and comment standards