Module documentation guidelines

Last updated January 31, 2012. Created by raspberryman on July 21, 2007.
Edited by goron, rosell.dk, dman, wmostrey. Log in to edit this page.

When submitting (or maintaining) modules, good documentation is vital in order for the module to receive a wide user base and help future developers expand on your module. The following guidelines should be used when coding modules that are to reside in the Drupal contributions repository.

See also embedded documentation style guide which contains the syntax to support some of the suggestions below.

Minimum requirements

Provide a useful README.txt. #

All modules should provide a README.txt file. This plain-text file should contain a basic overview of what the module does and how someone may use it. It should provide enough information for the user to evaluate whether it will suit their needs before they download and install the module.

• The README.txt file should repeat the synopsis on the project page on Drupal.org.
• The project page on Drupal.org should contain a direct link to the README.txt.
• Like all other module files, README.txt and other *.txt files, should use unix-style line-endings (\n), and not windows (\r\n) or mac (\r) line endings.
• The file should be formatted to hard-wrap at 80 characters with unix-style line-endings.

Provide help text in the Drupal UI. #

At both the end-user and coder/developer level, the Drupal help pages are the obvious place to access information about your module. All but the most trivial modules should implement hook_help(). See the Help standard for details on how to structure your help documentation.

• The following example code for Drupal 6 shows how to "inline" the README.txt file, displaying a line-break version of the file in the Drupal UI.
  
  <?php
/**
* Implements hook_help().
*/
function mymodule_help($path, $arg) {
  switch ($path) {
    case 'admin/help#mymodule':
      // Return a line-break version of the module README.txt
      return filter_filter('process', 1, NULL, file_get_contents( dirname(__FILE__) . "/README.txt") );
  }
}
?>

Provide tips to get new users started. #

The README.txt and hook_help should clearly describe administrative and end-user access, functionality, and module usage, showing new users where to get started, to find the new functionality provided by your module.

If the module provides general menu items (ie, non-admin interface links), list the paths, so the user doesn't have to search through the code or admin interface to find them.

If the module modifies existing user interface forms using Form API, tell the user what to look for to ensure it is working.

If the module requires configuration, provide a link to the settings page and write a small walkthrough on how to get it started.

Follow package naming conventions. #

In your module.info file, you have the ability to define a "package" group. Most modules should not use packages at all. Quoting from the Writing .info files page, "In general, this field should only be used by large multi-module packages, or by modules meant to extend these packages, such as CCK, Views, E-Commerce, Organic Groups and the like." If you do have a valid use for package name, please use the existing list of project groups to label your module, and be careful of case sensitivity.

Document all functions. #

You are expected to use Doxygen style comments throughout your module. Although sometimes it looks like so much boilerplate, it's those inline comments that power the entire api.drupal.org reference site and can do the same for you using the API module. Your code can be self-documenting ... for free!

• Many IDEs can automatically detect Doxygen doc-blocks, and provide context-sensitive help, not to mention the obvious advantages to people reading your code.
• Read the commenting guidelines and pay attention to the use of @ingroup described there.

Document hooks in a modulename.api.php #

If your module creates any hooks or has an associated API, add examples of these hooks in a file named modulename.api.php. This not only helps other developers understand the provided API a little easier, but also gives IDEs the hook information. In order for this to be useful, the hooks should be fully documented with doxygen comments about the parameters and return values. See Drupal core's system.api.php for an example of this.

Recommended practices. #

This list of suggestions may help to make your module more developer-friendly:

• Even if your module doesn't have a need for the hook_install() function, it is common to display a note confirming that the module is installed and ready for action, often providing a link to the administration/configuration page for your module (if it exists). The hook_install function belongs in your module's .install file.
  
  <?php
/**
* Implements hook_install().
*/
function mymodule_install() {
  drupal_set_message(st("Your Module settings are available under !link",
    array( '!link' => l(st('Administer > Site configuration > Your Module'),  'admin/settings/yourmodule/settings'))
  ));
}
?>
  
  Note that you should use st() rather than t() within .install files.
• Create links cross-referencing the module action page and its setting page (and help page). These locations are often 3 or 4 clicks away from each other! Using the hook_help method to add a paragraph at the top of related pages may help.
  Inline, context-sensitive cross-referencing is probably better documentation than any number of paragraphs in a third text document explaining how to get from A to B.
• If appropriate, add extra documentation as part of the project distribution, under a subdirectory called docs/. Alternatively, consider using the help/ subdirectory with static HTML-file documentation, as part of the emerging standards in the Advanced Help module.
• Screenshots of the user interface, or diagrams of the processes are especially helpful.
• Try installing and running your code through the API module.
  It's not perfect, but it shows the level of your current documentation, and what it could be if you reviewed your docblock formatting a little.
• If you are hosting your own development or Drupal demo site elsewhere online, consider making your code documentation available, and linking to it from your project page. This is also an Open source best practice. A proposal is afoot to integrate this functionality on drupal.org. If you do not have a demo site, consider requesting that your code be added to drupalcontrib.org, which adds API documentation for contributed drupal modules upon request.
• Install and run the Coder module over your code. This will ensure higher code quality, and coding standards, making your code easier to maintain between users.
• Use inline comments for hint, explanations, or reasoning of any potentially tricky bits of the code. They should hard-wrap at the 80 characters. Syntax looks like this:
  
    // On their own line, preceding their subject, using proper caps and
  // punctuation, wrapping at 80 characters.
  
  Inline comments are intended for and read mainly by maintainers and coders who wish to read the source code to gain deeper understanding of the module functionality. Contextual 'de-obfuscation' comments, TODOs, known limitations, notes-to-self, excuses for doing something the long way and 'gotcha' workaround warnings go here.
• Use Doxygen @see references liberally to link related functions. Function names and files are interpreted and linked, so no additional markup is required beyond the @see command itself.
• Keeping functions short (<1 page is good) means you shouldn't have to write up too much extra about the implementation details.
• Encourage contributors to help improve the documentation. Users are encouraged to contribute patches that clarify comments, and such a patch is harmless to fold into version control. Often another pair of eyes will see things that seem to need further explanation even when the developer is more familiar with the mechanics of the module.
• Writing a conceptual overview of the purpose of the code and its general methodology in the @file section is helpful to future developers. It may even help designing the code during the planning stages.

This page is a work in progress, so please contribute tips or suggest better alternatives as appropriate. Read or contribute to the original discussion.