Updating API documentation

Last updated June 9, 2011.

This document covers updating the API documentation at http://api.drupal.org/. This documentation is, with very few exceptions, generated from specially-formatted "Doxygen" comments in PHP files. There is a Drupal Doxygen reference available, and this page outlines the process of making change to api.drupal.org documentation. The steps are:

• Finding the source file the documentation is in
• Reporting the problem as an issue (if it isn't already reported), or
• Finding an issue to work on
• Fixing the issue with a patch

Finding the source file for API documentation

The documentation on api.drupal.org is built from the PHP source code in selected projects (Drupal core and a few others currently; there are plans eventually to have all contributed projects on api.drupal.org). So if you want to update API documentation, the first step is to figure out which project and file it comes from.

Currently, the easiest way to do that is to look at the URL of the documentation page. The first segment of the URL after api.drupal.org/api is the name of the project, and the next segments give the file name. For instance:

• The node_load() function is documented at http://api.drupal.org/api/drupal/modules--node--node.module/function/nod..., so it is part of the Drupal project (http://drupal.org/project/drupal) in file modules/node/mode.module.
• The node_example_entity_info_alter function is documented at http://api.drupal.org/api/examples/node_example--node_example.module/fun..., so it is part of the Examples for Developers project (http://drupal.org/project/examples), in file node_example/node_example.module.

At the time of this writing, there is one exception to this method for figuring out what project a given piece of documentation comes from. This exception is for URLs like: http://api.drupal.org/api/drupal/developer--hooks--core.php/function/hoo..., which would indicate that this function is part of the Drupal project in the "developer" directory. However, this directory doesn't exist in the Drupal project. These files used to be in a part of the contributions repository that was not part of a project, and they have now been moved to the Documentation project (http://drupal.org/project/documentation). The URLs for these pages will likely be changing soon to reflect this move.

Reporting problems with API documentation

Once you have located the project and file where the problem is, the next step is to make sure there is an issue filed that reports the problem. Before creating a new issue, you should search through the issue queue for the project containing the documentation, and make sure it hasn't already been reported. For example, if the problem is in the Drupal project, you can search for Drupal core Documentation issues for related keywords. If it is in a different project, go to the project page, and search issues from there.

If you determine that the issue hasn't been created yet, you can click the "Create a new issue" link on the issue search page and file a new issue. Most projects have a "documentation" component, which should be used to indicate that you are filing a documentation issue. Write a concise and complete description of the problem, and give it a clear title.

If you are looking at a documentation page on api.drupal.org, you can also use the "file an issue" link (at the very bottom, in the "Post new comment" header) to create a new issue. You will still need to fill in a title and a description of what the problem is.

Finding an API documentation issue to fix

If you want to help fix issues others have already identified and reported, you can find issues in Drupal core in the documentation component with this search: Search for Drupal/Documentation issues. You may also want to look at the issues in the Documentation project issue queue and the Examples for developers issue queue.

Fixing problems with API documentation

Once you have located the project, file, and issue you want to work on, if you have an idea for how the documentation should be fixed, you can do two things:

1. Add a comment to the issue explaining what the fix should be. If you are not sure your idea is correct, then you should probably stop there and wait for someone else to endorse your idea or suggest a new one, before proceeding.
2. If you are certain of the correct fix:
   1. Assign the issue to yourself, adding a comment explaining that you are working on the issue.
   2. Create a "patch" for the source file implementing the fix (see below).
   3. Attach the patch to the issue in a comment, setting the status of the issue to "needs review", and un-assigning it.
   4. Someone (and possibly the automatic testing bot) will then review and/or test your patch, and if it is correct, eventually it will be committed to the source code repository.

Creating patches

The source files for all Drupal projects are managed using the Git source code control system. We have an extensive Git handbook available, and once you are familiar with the basics, you can use the Patch contributor guide to learn how to create patches.

Background

• Instructions on testing and reviewing code: http://drupal.org/node/314199
• Git documentation: http://drupal.org/documentation/git
• Documentation standards for API documentation: http://drupal.org/node/1354