[module] API [documentation extraction system]

HOT TIP: this content is flagged as highly recommended !

Compatibility:

0
Project page quote (external)
Project page quoted on: 
2014-02-18

The API module was designed to produce the Drupal developer documentation available at api.drupal.org. You can set up your own API documentation site by following these instructions.

The API module implements a subset of the Doxygen documentation generator specification, with some Drupal-specific additions. Standards for how to write Drupal documentation that this module can parse (and that conforms to Drupal coding standards) are on http://drupal.org/node/1354.

Depends on modules [Drupal7]
Getting the Grammar Parser library installed and seen by the system can be tricky. For instructions on compatible versions please visit Grammar Parser Library [bridge].

The API documentation extraction module is used on this site for the OOE API documentation for the OOE = Object Oriented Examples = One Of Each object-oriented tutorial module.


There was a problem getting the API module to recognise explicit links to Drupal core functions (with URLs including an exclamation mark '!'):

It has been fixed in 7.x-1.x-dev from 2014-Feb-07 (thanks jhodgon).

TIP: There is in fact no need to reference Drupal core functions this tedious way, or to have a Drupal core version on your server, one can now just refer to them by name and with parameters and they will magically turn into links as long as you have a Drupal API reference branch setup under /admin/config/development/api/php_branches, which parses an external dump of the Drupal core API.


If you are creating an external Drupal API reference branch you MUST reset the Core compatibility field from the default 7.x to something like 7.26, or Drupal functions in the docs won't become links.

On @param docs without description

Often as one codes not every parameter needs (or gets) a description in the docs immediately.

You MUST separate @param lines by at least one line, even if you don't give a description.

Example: WRONG:

  /**
   * ...
   * @param array $form
   * @param array $form_state
   *
   * @return array
   *  Description of returned array.
   */

Yields something like:

_state
Parameters

array $form:

Return value

array Description of returned array.

Example: RIGHT (better, despite missing parameter descriptions):

  /**
   * ...
   * @param array $form
   *
   * @param array $form_state
   *
   * @return array
   *  Description of returned array.
   */

Yields something like:

Parameters

array $form:
array $form_state:

Return value

array Description of returned array.


On excluding files by regular expression

If you edit an API branch under /admin/config/development/api/branches you can exclude files by regular expressions, but I can't find stated anywhere what regular expression language is used.

Example: I use the convention of renaming a code file (sometimes after duplicating it) to have an underscore '_' as prefix to mark it is old, archival, in some sense broken, or a scratch file, like this:

_TheClass.php. 
_TheClass_PRE_MIGRATION.php. 

These sort nicely in my IDE on the '_' prefix, and leave a nice development record, but should be excluded from the generated module API docs. I found the following expression worked for this case (was accepted by the API module):

'^_([a-z]|[A-Z]|[0-9]|[_])+\.php$'

The API module description for excluding files says 'Include delimeters' but does not seem to say what the delimiters are; I found single quotes as shown above worked.

One can test regular expressions live at: http://www.regexpal.com/. These seemed to be compatible with the API module.


How to create an API Reference Branch to the Drupal7 examples project API

As explained here , to create automatic links to functions of the Examples for Developers for Drupal7 just use the following for the JSON dump: https://api.drupal.org/api/examples/full_list/7.

Example: reference to form_example_tutorial7() turns into link form_example_tutorial_7() at one of my Object-Oriented Examples (OOE) tutorial module generated API pages: OOE 7.x-1.x » ooe.module function » ooe_form_demo_submit($form, &$form_state).

Visit also