missing api.php file for hook documentation

Sure, here are some docs pages about this:

- https://drupal.org/coding-standards/docs#functions
- https://drupal.org/node/161085

All core modules have a *.api.php file that you can use as a template.

You can also use Module Builder to generate the scaffold for the api.php file.

Looks like a good start! Few things missing and need cleaning up:

1. +++ b/captcha.api.php
   @@ -0,0 +1,133 @@
   +/**
   + * The hook is the only required function if you want to integrate with the base CAPTCHA module
   + *
   + * Modules may make changes to the comment before it is saved to the database.
   + * Functionality depends on the first argument $op:
   + * 'list': you should return an array of possible challenge types that your module implements.
   + * 'generate': generate a challenge.
   + *  You should return an array that offers form elements and the solution
   + *    of your challenge, defined by the second argument $captcha_type.
   + *    The returned array $captcha should have the following items:
   + *    $captcha['solution']: this is the solution of your challenge
   + *    $captcha['form']: an array of the form elements you want to add to the form.
   + *      There should be a key 'captcha_response' in this array, which points to
   +  *      the form element where the user enters his answer.
   + *    An optional additional argument $captcha_sid with the captcha session ID is
   + *    available for more advanced challenges (e.g. the image CAPTCHA uses this
   + *    argument, see image_captcha_captcha()).
   + **/
   +
   +/**
   + * Implementation of hook_captcha().
   + */
   +function hook_captcha_captcha($op, $captcha_type='') {
   

   You should have only one docblock for each function. The 'Implementation...' one should be removed.

2. +++ b/captcha.api.php
   @@ -0,0 +1,133 @@
   +function foo_captcha_captcha($op, $captcha_type='') {
   

   Parameters and return need to be documented.

From the docs:

The summary starts with an imperative verb that tells why a module would want to implement the hook. Example: "Respond to node deletion." Hook definitions are placed in a .api.php file, which is not directly loaded by Drupal. Each is a fake function whose name starts with "hook", and whose function body is a sample implementation. Parameters and return value that the implementer must use need to be documented.

So for example:

/**
 * Declare system queues to be usable by human workers.
 *
 * @return
 *  An array keyed by the queue name, where each item is an array of data about
 *  the queue containing the following properties:
 *  - 'queue': The queue name.
 *  - 'label': A human-readable label for the queue. This needn't include the
 *    word 'queue'; UI texts add this in their phrasing, as in 'The foo queue'.
 *  - 'lease time': The lease time to grant when claiming an item from the queue
 *    for human workers. This should be long enough for the user to read the
 *    form, go and make a cup of tea, and so on. Suggested time is 30 minutes.
 *  - 'entity type': The type of the entities being queued.
 *  - 'entity operations': An array of the names of operations to be made
 *    available in the queue item processing form. These should also be defined
 *    in hook_entity_operation_info(), where their handlers and other properties
 *    should be set.
 *  - 'view mode': (optional) The view mode in which to display the entity in
 *    the queue processing form. Defaults to 'full', the same as entity_view().
 *    Entities using this system may wish to provide a view mode for this which
 *    suppresses the output of the entity title as a link.
 */
function hook_human_queue_worker_info() {
  $info = array(
    'my_queue' => array(
      'queue' => 'my_queue',
      'label' => t("Dummy"),
      'lease time' => 30 * 60,
      'entity type' => 'entity_operations_test',
      'entity operations' => array(
        // These should be operations defined on the entity.
        'red',
        'blue',
        'lookup',
        'delete_confirm',
        'skip',
      ),
      'view mode' => 'queue_process',
    ),
  );

  return $info;
}