Updating API documentation

This document covers updating the API documentation at http://api.drupal.org/.

How api.drupal.org is generated

The documentation at api.drupal.org is generated from two sources.

All documentation for core functions, constants, and files is automatically generated from specially-formatted "Doxygen" comment headers appearing at the tops of files, and before functions and constants, in the core Drupal PHP files. Examples:

• http://api.drupal.org/api/5/constant/DRUPAL_BOOTSTRAP_EARLY_PAGE_CACHE
• http://api.drupal.org/api/5/function/node_load
• http://api.drupal.org/api/5/file/modules/book/book.module

There is also some documentation on api.drupal.org that does not pertain directly to functions that Drupal loads. This includes:

• Hook documentation, such as http://api.drupal.org/api/function/hook_search/5
• Special pages, such as http://api.drupal.org/api/file/developer/topics/forms_api_reference.html

Depending on the version of Drupal, this documentation could be in special files whose names end in api.php that are within the core Drupal source tree, or it could be in files that are completely outside the core Drupal source tree.

It is usually easy to figure out where a given api.drupal.org documentation page is coming from: At the top of most pages, just under the tabs that let you choose which Drupal version you want to use, there is a line telling which file the documentation comes from. If the file name starts with "include/", "module/", or some other directory that is part of Drupal core, then the function documentation is inside the Drupal source code tree. If it starts with "developer", then it is in a separate "contributions" source code tree. If there is no file line, then the documentation is probably an HTML file that is located in the "contributions" tree.

Both of the trees are managed via CVS repositories. Read the CVS introduction handbook page to find out more about accessing these two repositories. Note that API documentation in the "contributions" repository is in the "docs/developer" directory in that repository. The HTML files for the Forms API and things like that are in directory docs/developer/topics; other documentation should have a file header on its api.drupal.org page, telling you where it is located. You might want to check out only the docs/developer section of the contributions repository, because the whole repository is huge. E.g.:

Reporting and fixing problems

If you find a minor problem that is located in the "contributions" repository, and you have a CVS account, you can fix the problem directly by following the instructions on the CVS introduction handbook page. Be sure to include a meaningful comment when you commit your changes.

For bigger changes in the "contributions" repository, for any changes in the core Drupal repository, or if you do not have a CVS account to commit your minor change in the "contributions" repository, you will need to create a Drupal core issue and select the Documentation component. Include a consise and complete description of the problem in the description section.

If you want to help fix issues others have already identified and reported, you can find issues in Drupal core tagged as the Documentation component with this search: Search for Drupal/Documentation issues.

Once your issue is created, if you know how to make the documentation correct and want to work on it (or if you have found an issue someone else reported that you want to work on), assign the issue to yourself. Next, research and figure out how the documentation should be updated. When you have the solution complete, create a patch file and attach it to the issue.

If the issue applies to more than one version of Drupal, you will need to make patches for each branch of the repository. Check the CVS branches and tags handbook page for information about how to deal with branches.

Also note that if you file a Drupal core issue against the current development version, and attach a patch file, there is now a process that runs automatically that tries to apply your patch to the Drupal source code tree. It will generate an error (and change the status of your issue) if the patch fails to apply. So if you attach patches for previous branches of Drupal, or patches that need to be applied to the "contributions" repository rather than to the core Drupal repository, you should change the file name. There is a help note near the "Attach file" area of the Issue edit screen that explains how to change the file name (or you can just give it a .txt extension instead of .patch or .diff).

After creating and attaching patches, if the issue is in the "contributions" repository and you have a CVS account, you can apply your patches. When you commit your changes, include the issue number (i.e. node ID) in your CVS commit log messages. This will let other developers track what you have done. You can then change the status of the issue to "Fixed", and remove yourself as the assigned person.

If you cannot commit your patch, or if the issue is in the core repository, change the issue's status to "Patch (code needs review)" and remove the assignment to yourself. You might want to monitor the issue in case questions come up.