As this module invents hooks for other modules to implement, it should have an api.php file to document them.

Files: 
CommentFileSizeAuthor
#5 captcha-missing_api_.php_file_for_hook_documentation-1988950-5.patch5.32 KBnagwani
FAILED: [[SimpleTest]]: [MySQL] Invalid PHP syntax in sites/default/modules/captcha/captcha.api.php.
[ View ]

Comments

Could you please provide a link to documentation on how to implement this, or provide a patch?

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.

StatusFileSize
new4.6 KB
FAILED: [[SimpleTest]]: [MySQL] Invalid PHP syntax in sites/default/modules/captcha/captcha.api.php.
[ View ]

Attaching .api.php. Created from api.txt file. Please review.

Status:Active» Needs work

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.

StatusFileSize
new4.69 KB
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch interdiff_36.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]
new5.32 KB
FAILED: [[SimpleTest]]: [MySQL] Invalid PHP syntax in sites/default/modules/captcha/captcha.api.php.
[ View ]

Updated.

Issue summary:View changes
Status:Needs work» Needs review

The last submitted patch, 5: interdiff.patch, failed testing.

Status:Needs review» Needs work

joachim, are you saying that the "Implementation..." blocks need to be removed and not replaced by anything else?

Updating shown files...

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;
}