State of the API module

I talked with a few people interested in API.drupal.org improvements at DrupalCon D.C. This post outlines the details of what I want to see done. Some tasks, like commenting on API pages, seem simple, however there are time-consuming details.

This comprehensive list is a lot of work. It will not get done quickly without help. I am organizing a Drupal.org redesign sprint April 8 to 11 or 12 in San Francisco, some API module work will likely be done April 11 and 12. Email me if you are interested in attending. I will be attending the documentation planning sprint in Toronto to work with the larger documentation project.

I would like to see more people, particularly Drupal shops, using API module. More users means more contributors. For example, Development Seed is trying out API with Spaces on their Code site. I talked with Young about the implementation and the scalability to 4000 modules.

Parser rewrite

How the parser should work:

1. Divide code into pairs of documentation comments and code.
2. Process documentation comment @tags and formatting. Save structured data.
3. On render, process dynamic links, code in other files may have moved around since parsing.

The first pass is being rewritten. The second pass needs work, a rewrite may not be necessary. The third pass is okay, I worked on it last year.

Tasks

Document all contrib modules

Dries mentioned he wants this. It would be a great resource with the importance of modules in Drupal. The huge number of modules with flexible branches and tags, makes searching the entire codebase impractical; API module can fill that gap. It would be another tool for determining module quality, which is currently a pain point for Drupal site builders.

Tasks

• Database structure to keep track of projects
• Manage CVS integration with update status XML
• UI to separate projects
• Do something smart when @mainpage is not there
• Linking across projects
• Searching within and across projects
• Regexp search for security and other research

Comments

People want comments like PHP.net. This is a new social feature and needs social consideration in addition to technical. I want the best information to be in the documentation, not buried in comments. I see API.drupal.org as a reference site, it should quickly answer questions and get out of the way.

Tasks

• Easy Drupal.org issue creation to improve documentation
• Single sign on, it would be irresponsible to make another login
• Comments on API objects, likely through nodes
• Comment policy
• Comment policy enforcement plan
• Spam protection

UI improvements

The user interface has a lot of room to improve. I would like Drupal's documentation to be an excellent example of what is possible when you have a big database of code.

Tasks

• Object documentation and browsing
• Make Drupal conventions, like hooks, themeable functions, and callbacks obvious
• Code should always use tag
• Link to URLs
• Instant auto-complete
• Improve browsing pages
• Documentation coverage and accuracy
• API changes between versions
• API link filter for 3rd-party sites