OBSOLETE - API Site Plans and Ideas

This page is obsolete!

This page (and section) are obsolete. As of spring 2014, the Documentation Working Group (DocWG) has taken over the decisions and planning for tools, policies, and procedures for Drupal documentation. The DocWG maintains a section containing the current goals, priorities, and projects of the Documentation Working Group.

Prior content of this page

The API reference site on api.drupal.org is an invaluable reference for Drupal coders and themers. It is built using the API module.

There are some improvements that could be made to the documentation process and correspondingly to the API module. This page collects some thoughts about these improvements.

Note: This page tends to get out of date, since the API module is under active development. For the most up-to-date priorities, your best bet is to search the API module's issue queue for issues whose priority has been set to "major" or "critical". The maintainers of the API module regularly update the priorities of issues, so that is what is most likely to be up to date. The list here is still useful though, as it gives an overview and some insight.

UI, Navigation, and Links

One of the nice things that the API site does is that when we're looking at a page, functions, methods, constants, and files in the comment block that makes up the text of the page, as well as the function body, turn into links. Another thing it does is make it possible to see how the function has changed in different versions of Drupal. But there are a couple of things that could be improved:

• Class/method pages:
  #793958: Show which class a method/member variable is in
  #1070090: Show/Hide Inherited Methods
• Cross-project linking (e.g. between Drupal Core and Examples for Developers):
  #990108: Links and search do not make sense and are not working across projects
• More accurate linking within projects:
  #1485848: Make reference links and type inferences from @return/@param/@var data types in docs

Documentation Parsing

The API module supports a subset of Doxygen, with some Drupal-specific standards and additions. Here are some additions we'd like to make to what we can do in documentation headers:

• Support namespaces
  #1507476: Support namespaces in API module
• Generate pages like the Forms API reference from code comments, rather than trying hopelessly to maintain it as a giant HTML page:
  #100680: [meta] Make API module generate Form API documentation
• Other core files that we are not parsing currently (JavaScript, for instance):
  #25901: Parse/save/display JavaScript files
• Other documentation parsing suggestions:
  #996242: Support @ref, @section and @subsection tags
  #839550: Ability to add documentation headers to global listing pages (Classes, Functions, etc.)
  #265301: Support of @verbatim tags