I have been volunteering my time with the open-source Drupal web software project for many years, helping at various times with code writing, reviewing, and testing; documentation writing and editing; and managing subsets of the project. One of the volunteer roles I am most proud of is that for the past five years or so, I've been co-maintainer of the API module, which is the software behind the Drupal API documentation site, api.drupal.org. If you're a Drupal programmer, you're probably familiar with this site, where you can go to find API documentation for the PHP classes and functions in even very old versions of Drupal. But you may not be aware of all of its useful features, some of which were added to the site quite recently... so I thought I would write up a list of my favorite features and ways to use the site. Warning: I haven't made any attempt to explain technical terms here -- this list is aimed at Drupal programmers. For an introduction to Drupal programming... of course I would suggest you get my book, Programmers Guide to Drupal.
- Searching
- On every page of the site, there is a search box at the top of the sidebar, where you can type in the name of a class, function, etc. It has an autocomplete feature, so you can see matches as you type, but once you finish typing and search, you can search for both partial and complete matches. I think most people know about this way of searching, which is a great way to find documentation for a function or class that you know the name of. What you might not have noticed is that there is a second search form in the header of the site. That search form performs a full-text search on documentation, so it is useful for finding functions and classes when you don't even know their names. You can also access these search results from the search form on the main drupal.org web site, mixed in with other Drupal documentation, forums, etc. Try it out!
- Topics
- Starting with Drupal 8 (and to a lesser extend in previous versions of Drupal), if you go to the landing page for the branch of interest (such as 8.3.x, 8.4.x, etc.), you will find a list of topics, which will guide you through learning the basics of the Drupal API. (This is another Drupal volunteer effort I'm quite proud of: early in the Drupal 8 cycle, Angie "webchick" Byron and I sat down at a Drupal conference and decided on a preliminary list of topics that needed to be on that page, and by the time Drupal 8.0.0 was released, several other volunteers and I had managed to get them written. They've since been expanded and revised.)
- Form/render elements page
- If you've been using Drupal for a while, you've probably visited the Form API reference page at least once. It lists most or all of the "elements" you can put into Drupal forms, and documents them... to some extent. Unfortunately, it was written as a very large, flat HTML file, and it's nearly impossible to maintain, so it's not complete or totally accurate (it is such a maintenance nightmare, that I almost wrote "the dreaded Form API reference page" earlier in this paragraph). In Drupal 8, this has been replaced by an Elements page, which you can find by going to the landing page for a branch (8.2.x, 8.3.x, etc.) and clicking on "Elements" in the right sidebar. This page lists all the form elements, plus render elements, and you can click through to get more documentation. Since the documentation is maintained with the form/render element classes, it's much more likely to be correct than the old reference page.
- Listing pages
- Each branch on the site has a collection of "listing" pages, such as Functions, Classes, etc. There are several new listing pages for Drupal 8, including a Services page and a listing of classes and functions that have been marked as Deprecated. Also, relatively recently, these listing pages were converted to use the Views module, which allowed the addition of many sorting and filtering options. For instance, if you go to the Drupal 8.4.x Classes listing page, you can filter by name or namespace (with partial matching), or sort by number of uses, to find a list of the most popular classes. Another useful example: You can go to the Deprecated listing page, and sort by one of the four right columns to find deprecated functions, methods, and classes that are still being used in the codebase.
- Cross-linking
- Some documentation includes See Also links to relevant topics and other functions, classes, etc. Also, as much as possible, automatic links are made in both documentation text and code listings.
- N functions call this, etc.
- It's been possible on the site for many years to see a list of which functions call a given function. For instance, if you're on the page for the Drupal 7 check_plain() function, you can see a list of all 186 functions that call it. What you might not realize is that there are now many other "references" listings on the site, including:
- Strings containing the names of functions, classes, form/render element IDs, YML configuration files, and Drupal 8 services
- Use statements for classes, interfaces, and traits
- Implementations and invocations of hooks, including theme hooks
- Classes that implement interfaces
- Full class hierarchy for classes, including both "parent" and "child" classes
- Overrides of class methods
- Usage of constants in code
- Drupal 8 plugin classes that are declared to be of a given annotation type
I hope everyone learned something new about api.drupal.org from this article -- happy programming!