Issue #1347914 by Albert Volkman, Lars Toomre, batigolix, NROTC_Webmaster, xjm, sven.lauer: Fix up API docs for Filter module

1 files changed, 54 insertions, 11 deletions

diff --git a/modules/filter/filter.admin.inc b/modules/filter/filter.admin.inc
index 5a21e6e2e..60284d993 100644
--- a/modules/filter/filter.admin.inc
+++ b/modules/filter/filter.admin.inc
@@ -2,13 +2,14 @@
 
 /**
  * @file
- * Admin page callbacks for the filter module.
+ * Administrative page callbacks for the Filter module.
  */
 
 /**
- * Menu callback; Displays a list of all text formats and allows them to be rearranged.
+ * Page callback: Form constructor for a form to list and reorder text formats.
  *
  * @ingroup forms
+ * @see filter_menu()
  * @see filter_admin_overview_submit()
  */
 function filter_admin_overview($form) {
@@ -45,6 +46,9 @@ function filter_admin_overview($form) {
   return $form;
 }
 
+/**
+ * Form submission handler for filter_admin_overview().
+ */
 function filter_admin_overview_submit($form, &$form_state) {
   foreach ($form_state['values']['formats'] as $id => $data) {
     if (is_array($data) && isset($data['weight'])) {
@@ -95,7 +99,26 @@ function theme_filter_admin_overview($variables) {
 }
 
 /**
- * Menu callback; Display a text format form.
+ * Page callback: Displays the text format add/edit form.
+ *
+ * @param object|null $format
+ *   (optional) An object representing a format, with the following properties:
+ *   - format: A machine-readable name representing the ID of the text format
+ *     to save. If this corresponds to an existing text format, that format
+ *     will be updated; otherwise, a new format will be created.
+ *   - name: The title of the text format.
+ *   - cache: (optional) An integer indicating whether the text format is
+ *     cacheable (1) or not (0). Defaults to 1.
+ *   - status: (optional) An integer indicating whether the text format is
+ *     enabled (1) or not (0). Defaults to 1.
+ *   - weight: (optional) The weight of the text format, which controls its
+ *     placement in text format lists. If omitted, the weight is set to 0.
+ *     Defaults to NULL.
+ *
+ * @return
+ *   A form array.
+ *
+ * @see filter_menu()
  */
 function filter_admin_format_page($format = NULL) {
   if (!isset($format->name)) {
@@ -109,11 +132,24 @@ function filter_admin_format_page($format = NULL) {
 }
 
 /**
- * Generate a text format form.
+ * Form constructor for the text format add/edit form.
+ *
+ * @param $format
+ *   A format object having the properties:
+ *   - format: A machine-readable name representing the ID of the text format to
+ *     save. If this corresponds to an existing text format, that format will be
+ *     updated; otherwise, a new format will be created.
+ *   - name: The title of the text format.
+ *   - cache: An integer indicating whether the text format is cacheable (1) or
+ *     not (0). Defaults to 1.
+ *   - status: (optional) An integer indicating whether the text format is
+ *     enabled (1) or not (0). Defaults to 1.
+ *   - weight: (optional) The weight of the text format, which controls its
+ *     placement in text format lists. If omitted, the weight is set to 0.
  *
- * @ingroup forms
  * @see filter_admin_format_form_validate()
  * @see filter_admin_format_form_submit()
+ * @ingroup forms
  */
 function filter_admin_format_form($form, &$form_state, $format) {
   $is_fallback = ($format->format == filter_fallback_format());
@@ -287,7 +323,9 @@ function theme_filter_admin_format_filter_order($variables) {
 }
 
 /**
- * Validate text format form submissions.
+ * Form validation handler for filter_admin_format_form().
+ *
+ * @see filter_admin_format_form_submit()
  */
 function filter_admin_format_form_validate($form, &$form_state) {
   $format_format = trim($form_state['values']['format']);
@@ -304,7 +342,9 @@ function filter_admin_format_form_validate($form, &$form_state) {
 }
 
 /**
- * Process text format form submissions.
+ * Form submission handler for filter_admin_format_form().
+ *
+ * @see filter_admin_format_form_validate()
  */
 function filter_admin_format_form_submit($form, &$form_state) {
   // Remove unnecessary values.
@@ -336,10 +376,14 @@ function filter_admin_format_form_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; confirm deletion of a format.
+ * Form constructor for the text format deletion confirmation form.
  *
- * @ingroup forms
+ * @param $format
+ *   An object representing a text format.
+ *
+ * @see filter_menu()
  * @see filter_admin_disable_submit()
+ * @ingroup forms
  */
 function filter_admin_disable($form, &$form_state, $format) {
   $form['#format'] = $format;
@@ -353,7 +397,7 @@ function filter_admin_disable($form, &$form_state, $format) {
 }
 
 /**
- * Process filter disable form submission.
+ * Form submission handler for filter_admin_disable().
  */
 function filter_admin_disable_submit($form, &$form_state) {
   $format = $form['#format'];
@@ -362,4 +406,3 @@ function filter_admin_disable_submit($form, &$form_state) {
 
   $form_state['redirect'] = 'admin/config/content/formats';
 }
-