Voting starts in March for the Drupal Association Board election.
Last updated March 1, 2013.
This document covers updating the Drupal API documentation at http://api.drupal.org/. This documentation is, with very few exceptions, generated from specially-formatted "docblock" comments in PHP files. There is a Drupal API documentation standards guide 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 http://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.
The easiest way to do that is to look at the documentation page. The first segment of the URL after api.drupal.org/api is the name of the project (this is also in the page header and other blocks.
The file name is shown on the page in a section marked "File", and this is relative to the root of the project. For instance: Let's say you are on the node_load() page in Drupal 7 and you find a problem:
- The first part of the URL is api.drupal.org/api/drupal, and the navigation blocks on the right say "Drupal 7", so you are in the Drupal project version 7.
- Scrolling down, the File section of the page says "modules/node/node.module, line 967" -- so that is where this function is, within the Drupal 7 code repository.
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 pages like hook_menu() in Drupal 6. The navigation and URL show this as being part of the Drupal project, but the File section says "developer/hooks/core.php, line 1338". If you look at the Drupal 6 code base, you will not find this file. Instead, it's actually part of the Documentation project's git repository.
Also, you may find that the documentation is part of a third-party library adopted into Drupal, such as Symfony (for Drupal 8 and later versions). For instance, if the File line is
core/vendor/symfony/..., it is part of the Symfony project. In this case, you will not be able to follow the rest of the steps below to fix the API documentation -- you'll need to contribute the issue report and fix to the third-party project. We have a separate page on how to contribute to Symfony API documentation.
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:
- 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.
- If you are certain of the correct fix:
- Assign the issue to yourself, adding a comment explaining that you are working on the issue.
- Create a "patch" for the source file implementing the fix (see below).
- Attach the patch to the issue in a comment, setting the status of the issue to "needs review", and un-assigning it.
- 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.
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.