Drupal Module Documentation Recommendations

When submitting (or maintaining) modules for an open source project like Drupal, good documentation for those that come after you is vital. There are many good books and resources out there, and any coder worth their salt will have opinions on what makes good documentation. There's always a line to be drawn between not enough and too much.

Following is a set of guidelines specifically for Drupal Modules that are to live in the Drupal contributions repository.

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.

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. It's also good to 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 to a user as to 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 it does

The README and/or the help should describe how to access the modules 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 UI forms using Form API tell the user what to look for to ensure it's working.
If the module requires configuration provide a link to the settings page and maybe write-up 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 atention 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 confiriming that the module is installed and ready for action.
  
  <?php
/**
* Implementation of hook_install().
*/
function mymodule_install() {
  drupal_set_message(t("YourModule settings are available under !link",
    array( '!link' => l('Administer > Site configuration > Your Module ',  'admin/settings/yourmodule/settings' ) )
  ));
}
?>
• Create links cross-referencing between 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 calls docs/
• Screenshots of the UI, 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! Open source at its best. A proposal is afoot to integrate this functionality on drupal.org
• Install and run the coder.module over your code. It's downright picky, but 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-obsfucation' 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. It's totally appropriate for a user to contribute a patch that does nothing but 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 when you (of course) are more familiar with how things are working.
• Writing a conceptual overview of the purpose of the code and its general methodology in the @file section is often a really helpful idea. It may even help designing the code during the planning stages.