Module documentation guidelines

When submitting (or maintaining) modules, good documentation for those that come after you is vital in order for the module to receive a wide user base. The following guidelines should be used when coding modules that are to live in the Drupal contributions repository.

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

Minimum requirements

Have a useful README

All but the most simple modules should come with a README.txt file. This should contain a basic overview of what the module does and how someone may use it. This may be a direct repeat of the synopsis on the project page. Also link directly to the README from the project page using a link of the form:
http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/modulename/...
This file should give enough information for user to evaluate whether it will suit their needs before they download and install the module.

Use hook_help

All but the most simple modules should implement hook_help() to some extent. See the Embedded documentation style guide for how to structure your documentation. Alternatively, you may simply inline the README using a function like:

<?php
/**
* Implementation of hook_help().
*/
function mymodule_help($section) {
  switch ($section) {
    case 'admin/help#mymodule':
      // Return a line-break version of the module README
      return filter_filter('process', 2, NULL, file_get_contents( dirname(__FILE__)."/README.txt") );
  }
}
?>

The Drupal help pages are the obvious place to access information about your module, at either a user or coder level.

Tell the user what the module does

The README and/or the help should describe how to access the module's functionality.
If it provides a few new menu items, list the paths, so the user doesn't have to go searching to find them in the admin interface.
If it 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.

Think about the package name

In your module.info file, you have the ability to define a 'package' group. Most modules should not use package 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 properly

You are expected to use Doxygen style comments throughout your modules. Although sometimes it looks like so much boilerplate, learn to love it, as 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!
Also, 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.

Recommended practices

This list of suggestions is not canonic, but may help to make your module more developer-friendly

• Even if your module doesn't have need of a hook_install function, it's nice to display a note confirming that the module is installed and ready for action. The hook_install function belongs in your module's .install file.
  
  <?php
/**
* Implementation of hook_install().
*/
function mymodule_install() {
  drupal_set_message(st("YourModule settings are available under !link",
    array( '!link' => l('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.
• When setting up your project page, enable the link to "Browse CVS Repository"
• If appropriate, feel free to add extra documentation as part of the project distribution, under a subdirectory called docs/
• Screenshots of the user interface, or diagrams of the processes are especially helpful. Even if you can't place inline images in your project page, you can link directly to extended documentation in the CVS for illustrations and user guides.
• 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.
• Install and run the coder.module over your code. This will make your code easier to maintain between users.
• Use inline comments
  
  // On their own line, preceding their subject, using proper caps and punctuation.
  
  to explain any potentially tricky bits of the code.
  Docs here are for maintainers and actual coders, who (hopefully) will read the source as easily as any prose around it. 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.
• 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 CVS. 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 non-canonic work in progress, so please contribute tips or suggest better alternatives as appropriate. Read or contribute to the original discussion.