Index: mollom.api.php
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/mollom/mollom.api.php,v
retrieving revision 1.1.2.5
diff -u -p -r1.1.2.5 mollom.api.php
--- mollom.api.php	5 Aug 2010 02:22:45 -0000	1.1.2.5
+++ mollom.api.php	16 Aug 2010 22:41:08 -0000
@@ -215,422 +215,6 @@
  */
 
 /**
- * @defgroup mollom_api Mollom API
- * @{
- * Functions to integrate with Mollom form protection.
- *
- * In general, there are two different kinds of form submissions:
- * - Entities created out of form submissions, which can be edited or deleted
- *   afterwards; whereas "entity" just refers to a uniquely identifiable data
- *   record.
- * - Form submissions that do not store any data, such as contact form mail
- *   messages and similar forms. While there may be an entity type (e.g.,
- *   "contact_mail"), there is no unique id for the post, which could be
- *   referred to later on.
- *
- * The Mollom API therefore supports two types of integration:
- * - Entity form integration: Mollom integrates with the add/edit form for an
- *   entity, and additionally with the delete confirmation form of the entity
- *   to send feedback to Mollom. Almost everything happens in an automated way,
- *   solely based on the information provided via Mollom's info hooks, as
- *   explained below.
- * - Free integration: Mollom integrates with a given form_id without 'entity'.
- *   Allowing users to send feedback requires to manually add "report to Mollom"
- *   links. Additionally requires to specify a 'report access [callback]' and
- *   'report delete callback' to correctly handle access to report and delete
- *   a posted piece of content. An example for this kind of integration can be
- *   found in contact_mollom_form_list(), mollom_mail_alter(), and related
- *   functions. This kind of integration is discouraged; it is recommended to
- *   implement and integrate with entity forms.
- *
- * Considering a very simple Instant Messaging module ("IM") that implements a
- * "im_message_form" allowing to send or edit an instant message, which should
- * be possible to be protected by Mollom:
- * @code
- * function im_message_form(&$form_state, $im) {
- *   // To allow other modules to extend this form more easily and simplify our
- *   // own form submission handling, we use the dedicated parent key "im" for
- *   // all message properties (allows for easy casting from array to object).
- *   // Also helps us to explain handling of hierarchical sub-keys. :)
- *   $form['#tree'] = TRUE;
- *
- *   // This is the stored message id (or 'post_id'), if any:
- *   // @see im_message_form_submit()
- *   $form['im']['id'] = array(
- *     '#type' => 'value',
- *     '#value' => isset($im->id) ? $im->id : NULL,
- *   );
- *   $form['im']['subject'] = array(
- *     '#type' => 'textfield',
- *     '#title' => t('Subject'),
- *     '#default_value' => isset($im->subject) ? $im->subject : '',
- *   );
- *   $form['im']['body'] = array(
- *     '#type' => 'textfield',
- *     '#title' => t('Message'),
- *     '#default_value' => isset($im->body) ? $im->body : '',
- *   );
- *   $form['actions']['submit'] = array(
- *     '#type' => 'submit',
- *     '#value' => t('Send'),
- *   );
- *   return $form;
- * }
- * @endcode
- *
- * "entity" refers to an entity type. For example, "node", "user", "comment",
- * but also "webform_submission". It is not necessarily the name of a database
- * table, but most often it actually is. The string is only used internally to
- * identify to which module a form submission belongs. Once in use, it should
- * not be changed.
- *
- * Our form accepts an argument $im, which we assume is the entity being created
- * or edited, so we can also assume the following submit handler:
- * @code
- * function im_message_form_submit($form, &$form_state) {
- *   // Do whatever we need to do to insert or update the message.
- *   $im = (object) $form_state['values']['im'];
- *   im_save($im);
- *   // Ensure subsequent submit handlers have an entity id to work with, as
- *   // newly created messages will not have an id in the form values.
- *   $form_state['values']['im']['id'] = $im->id;
- * }
- * @endcode
- *
- * The form values will not contain an entity id for a newly created message,
- * which is usually an auto_increment column value returned from the database.
- * Whenever a form submission is related to the entity (e.g., leads to a stored
- * entity being created, updated, or deleted) the form should *always* contain
- * the entity id in the same location of the submitted form values.
- * Above example therefore purposively assigns the new id after inserting it.
- *
- * @code
- * function im_message_delete_confirm_form(&$form_state, $im) {
- *   $form['#im'] = $im;
- *
- *   // Always provide entity id in the same form key as in the entity edit form.
- *   $form['im']['id'] = array('#type' => 'value', '#value' => $im->id);
- *
- *   // In our case, we also need to enable #tree, so that above value ends up
- *   // in 'im][id' where we expect it.
- *   $form['#tree'] = TRUE;
- *
- *   return confirm_form($form,
- *     t('Are you sure you want to delete %title?', array('%title' => $im->subject)),
- *     'im/' . $im->id,
- *     NULL,
- *     t('Delete')
- *   );
- * }
- * @endcode
- *
- * The same applies to the delete confirmation form for the entity: it also
- * provides the entity id for form submit handlers.
- *
- * After ensuring these basics, the first step is to register the basic form_id
- * along with its title, entity type, as well as the form_id of the
- * corresponding delete confirmation form via hook_mollom_form_list():
- *
- * @code
- * function im_mollom_form_list() {
- *   $forms['im_message_form'] = array(
- *     'title' => t('Instant messaging form'),
- *     'entity' => 'im',
- *     // Specify the $form_id of the delete confirmation form that allows
- *     // privileged users to delete a stored message. Mollom will automatically
- *     // add form elements to send feedback to Mollom to this form.
- *     'delete form' => 'im_message_delete_confirm_form',
- *   );
- *   return $forms;
- * }
- * @endcode
- *
- * Since modules can provide many forms, only minimal information is returned
- * via hook_mollom_form_list(). All details about the form are only required and
- * asked for, if the site administrator actually enables Mollom's protection for
- * the form. Therefore, everything else is registered via
- * hook_mollom_form_info():
- *
- * @code
- * function im_mollom_form_info($form_id) {
- *   switch ($form_id) {
- *     case 'im_message_form':
- *       $form_info = array(
- *         // Identical to hook_mollom_form_list():
- *         'title' => t('Instant messaging form'),
- *         'entity' => 'im',
- *         // Optional: User permission list to skip Mollom's protection for.
- *         'bypass access' => array('administer instant messages'),
- *         // Optional: To allow textual analysis of the form values, the form
- *         // elements needs to be registered individually. The keys are the
- *         // field keys in $form_state['values']. Sub-keys are noted using "]["
- *         // as delimiter.
- *         'elements' => array(
- *           'im][subject' => t('Subject'),
- *           'im][body' => t('Message body'),
- *         ),
- *         // Required when either specifying 'entity' or 'elements': the keys
- *         // are predefined data properties sent to Mollom (see full list in
- *         // hook_mollom_form_info()), the values refer to field keys in
- *         // $form_state['values']. Sub-keys are noted using "][" as delimiter.
- *         'mapping' => array(
- *           // Required when specifying 'entity' above: Where to find the id of
- *           // the entity being posted, edited, or deleted.
- *           // Important: The following assignment means that Mollom is able to
- *           // find the message id of the created, edited, or deleted message
- *           // in $form_state['values']['im']['id'].
- *           'post_id' => 'im][id',
- *           // Required if the form or entity contains a title-alike field:
- *           'post_title' => 'im][subject',
- *           // Optional: If our instant message form was accessible for
- *           // anonymous users and would contain form elements to enter the
- *           // sender's name, e-mail address, and web site, then those fields
- *           // should be additionally specified. Otherwise, information from
- *           // the global user session would be automatically taken over.
- *           'author_name' => 'im][sender][name',
- *           'author_mail' => 'im][sender][mail',
- *           'author_url' => 'im][sender][homepage',
- *         ),
- *       );
- *       break;
- *   }
- *   return $form_info;
- * }
- * @endcode
- *
- * "elements" is a list of form elements, in which users can freely type text.
- * The elements should not contain numeric or otherwise predefined option
- * values, only text actually coming from user input. Only by registering
- * "elements", Mollom is able to perform textual analysis. Without registered
- * form elements, Mollom can only provide a CAPTCHA.
- *
- * "mapping" is a mapping of form elements to predefined XML-RPC data properties
- * of the Mollom web service. For example, "post_title", "author_name",
- * "author_id", "author_mail", etc. Normally, all form elements specified in
- * "elements" would be merged into the "post_body" data property. By specifying
- * a "mapping", certain form element values are sent for the specified data
- * property instead. In our case, the form submission contains something along
- * the lines of a title in the "subject" field, so we map the "post_title" data
- * property to the "subject" field.
- *
- * Additionally, the "post_id" data property always needs to be mapped to a form
- * element that holds the entity id.
- *
- * @see mollom_node
- * @see mollom_comment
- * @see mollom_user
- * @see mollom_contact
- */
-
-/**
- * @defgroup mollom_api Mollom API
- * @{
- * Functions to integrate with Mollom form protection.
- *
- * In general, there are two different kinds of form submissions:
- * - Entities created out of form submissions, which can be edited or deleted
- *   afterwards; whereas "entity" just refers to a uniquely identifiable data
- *   record.
- * - Form submissions that do not store any data, such as contact form mail
- *   messages and similar forms. While there may be an entity type (e.g.,
- *   "contact_mail"), there is no unique id for the post, which could be
- *   referred to later on.
- *
- * The Mollom API therefore supports two types of integration:
- * - Entity form integration: Mollom integrates with the add/edit form for an
- *   entity, and additionally with the delete confirmation form of the entity
- *   to send feedback to Mollom. Almost everything happens in an automated way,
- *   solely based on the information provided via Mollom's info hooks, as
- *   explained below.
- * - Free integration: Mollom integrates with a given form_id without 'entity'.
- *   Allowing users to send feedback requires to manually add "report to Mollom"
- *   links. Additionally requires to specify a 'report access [callback]' and
- *   'report delete callback' to correctly handle access to report and delete
- *   a posted piece of content. An example for this kind of integration can be
- *   found in contact_mollom_form_list(), mollom_mail_alter(), and related
- *   functions. This kind of integration is discouraged; it is recommended to
- *   implement and integrate with entity forms.
- *
- * Considering a very simple Instant Messaging module ("IM") that implements a
- * "im_message_form" allowing to send or edit an instant message, which should
- * be possible to be protected by Mollom:
- * @code
- * function im_message_form(&$form_state, $im) {
- *   // To allow other modules to extend this form more easily and simplify our
- *   // own form submission handling, we use the dedicated parent key "im" for
- *   // all message properties (allows for easy casting from array to object).
- *   // Also helps us to explain handling of hierarchical sub-keys. :)
- *   $form['#tree'] = TRUE;
- *
- *   // This is the stored message id (or 'post_id'), if any:
- *   // @see im_message_form_submit()
- *   $form['im']['id'] = array(
- *     '#type' => 'value',
- *     '#value' => isset($im->id) ? $im->id : NULL,
- *   );
- *   $form['im']['subject'] = array(
- *     '#type' => 'textfield',
- *     '#title' => t('Subject'),
- *     '#default_value' => isset($im->subject) ? $im->subject : '',
- *   );
- *   $form['im']['body'] = array(
- *     '#type' => 'textfield',
- *     '#title' => t('Message'),
- *     '#default_value' => isset($im->body) ? $im->body : '',
- *   );
- *   $form['actions']['submit'] = array(
- *     '#type' => 'submit',
- *     '#value' => t('Send'),
- *   );
- *   return $form;
- * }
- * @endcode
- *
- * "entity" refers to an entity type. For example, "node", "user", "comment",
- * but also "webform_submission". It is not necessarily the name of a database
- * table, but most often it actually is. The string is only used internally to
- * identify to which module a form submission belongs. Once in use, it should
- * not be changed.
- *
- * Our form accepts an argument $im, which we assume is the entity being created
- * or edited, so we can also assume the following submit handler:
- * @code
- * function im_message_form_submit($form, &$form_state) {
- *   // Do whatever we need to do to insert or update the message.
- *   $im = (object) $form_state['values']['im'];
- *   im_save($im);
- *   // Ensure subsequent submit handlers have an entity id to work with, as
- *   // newly created messages will not have an id in the form values.
- *   $form_state['values']['im']['id'] = $im->id;
- * }
- * @endcode
- *
- * The form values will not contain an entity id for a newly created message,
- * which is usually an auto_increment column value returned from the database.
- * Whenever a form submission is related to the entity (e.g., leads to a stored
- * entity being created, updated, or deleted) the form should *always* contain
- * the entity id in the same location of the submitted form values.
- * Above example therefore purposively assigns the new id after inserting it.
- *
- * @code
- * function im_message_delete_confirm_form(&$form_state, $im) {
- *   $form['#im'] = $im;
- *
- *   // Always provide entity id in the same form key as in the entity edit form.
- *   $form['im']['id'] = array('#type' => 'value', '#value' => $im->id);
- *
- *   // In our case, we also need to enable #tree, so that above value ends up
- *   // in 'im][id' where we expect it.
- *   $form['#tree'] = TRUE;
- *
- *   return confirm_form($form,
- *     t('Are you sure you want to delete %title?', array('%title' => $im->subject)),
- *     'im/' . $im->id,
- *     NULL,
- *     t('Delete')
- *   );
- * }
- * @endcode
- *
- * The same applies to the delete confirmation form for the entity: it also
- * provides the entity id for form submit handlers.
- *
- * After ensuring these basics, the first step is to register the basic form_id
- * along with its title, entity type, as well as the form_id of the
- * corresponding delete confirmation form via hook_mollom_form_list():
- *
- * @code
- * function im_mollom_form_list() {
- *   $forms['im_message_form'] = array(
- *     'title' => t('Instant messaging form'),
- *     'entity' => 'im',
- *     // Specify the $form_id of the delete confirmation form that allows
- *     // privileged users to delete a stored message. Mollom will automatically
- *     // add form elements to send feedback to Mollom to this form.
- *     'delete form' => 'im_message_delete_confirm_form',
- *   );
- *   return $forms;
- * }
- * @endcode
- *
- * Since modules can provide many forms, only minimal information is returned
- * via hook_mollom_form_list(). All details about the form are only required and
- * asked for, if the site administrator actually enables Mollom's protection for
- * the form. Therefore, everything else is registered via
- * hook_mollom_form_info():
- *
- * @code
- * function im_mollom_form_info($form_id) {
- *   switch ($form_id) {
- *     case 'im_message_form':
- *       $form_info = array(
- *         // Identical to hook_mollom_form_list():
- *         'title' => t('Instant messaging form'),
- *         'entity' => 'im',
- *         // Optional: User permission list to skip Mollom's protection for.
- *         'bypass access' => array('administer instant messages'),
- *         // Optional: To allow textual analysis of the form values, the form
- *         // elements needs to be registered individually. The keys are the
- *         // field keys in $form_state['values']. Sub-keys are noted using "]["
- *         // as delimiter.
- *         'elements' => array(
- *           'im][subject' => t('Subject'),
- *           'im][body' => t('Message body'),
- *         ),
- *         // Required when either specifying 'entity' or 'elements': the keys
- *         // are predefined data properties sent to Mollom (see full list in
- *         // hook_mollom_form_info()), the values refer to field keys in
- *         // $form_state['values']. Sub-keys are noted using "][" as delimiter.
- *         'mapping' => array(
- *           // Required when specifying 'entity' above: Where to find the id of
- *           // the entity being posted, edited, or deleted.
- *           // Important: The following assignment means that Mollom is able to
- *           // find the message id of the created, edited, or deleted message
- *           // in $form_state['values']['im']['id'].
- *           'post_id' => 'im][id',
- *           // Required if the form or entity contains a title-alike field:
- *           'post_title' => 'im][subject',
- *           // Optional: If our instant message form was accessible for
- *           // anonymous users and would contain form elements to enter the
- *           // sender's name, e-mail address, and web site, then those fields
- *           // should be additionally specified. Otherwise, information from
- *           // the global user session would be automatically taken over.
- *           'author_name' => 'im][sender][name',
- *           'author_mail' => 'im][sender][mail',
- *           'author_url' => 'im][sender][homepage',
- *         ),
- *       );
- *       break;
- *   }
- *   return $form_info;
- * }
- * @endcode
- *
- * "elements" is a list of form elements, in which users can freely type text.
- * The elements should not contain numeric or otherwise predefined option
- * values, only text actually coming from user input. Only by registering
- * "elements", Mollom is able to perform textual analysis. Without registered
- * form elements, Mollom can only provide a CAPTCHA.
- *
- * "mapping" is a mapping of form elements to predefined XML-RPC data properties
- * of the Mollom web service. For example, "post_title", "author_name",
- * "author_id", "author_mail", etc. Normally, all form elements specified in
- * "elements" would be merged into the "post_body" data property. By specifying
- * a "mapping", certain form element values are sent for the specified data
- * property instead. In our case, the form submission contains something along
- * the lines of a title in the "subject" field, so we map the "post_title" data
- * property to the "subject" field.
- *
- * Additionally, the "post_id" data property always needs to be mapped to a form
- * element that holds the entity id.
- *
- * @see mollom_node
- * @see mollom_comment
- * @see mollom_user
- * @see mollom_contact
- */
-
-/**
  * Return information about forms that can be protected by Mollom.
  *
  * Mollom invokes this hook for all modules to gather information about forms