Issue #1326638 by sven.lauer, jhodgdon, xjm: Clean up API docs for field_ui() module.

7 files changed, 135 insertions, 69 deletions

diff --git a/modules/field_ui/field_ui-rtl.css b/modules/field_ui/field_ui-rtl.css
index 123a840bf..1066baa2f 100644
--- a/modules/field_ui/field_ui-rtl.css
+++ b/modules/field_ui/field_ui-rtl.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Right-to-left specific stylesheet for the Field UI module.
+ */
 
 /* 'Manage fields' overview */
 table.field-ui-overview tr.add-new .label-input {
diff --git a/modules/field_ui/field_ui.admin.inc b/modules/field_ui/field_ui.admin.inc
index e8152ea21..36c58f60c 100644
--- a/modules/field_ui/field_ui.admin.inc
+++ b/modules/field_ui/field_ui.admin.inc
@@ -51,7 +51,7 @@ function field_ui_fields_list() {
 }
 
 /**
- * Helper function to display a message about inactive fields.
+ * Displays a message listing the inactive fields of a given bundle.
  */
 function field_ui_inactive_message($entity_type, $bundle) {
   $inactive_instances = field_ui_inactive_instances($entity_type, $bundle);
@@ -72,9 +72,9 @@ function field_ui_inactive_message($entity_type, $bundle) {
 }
 
 /**
- * Helper function: determines the rendering order of a tree array.
+ * Determines the rendering order of an array representing a tree.
  *
- * This is intended as a callback for array_reduce().
+ * Callback for array_reduce() within field_ui_table_pre_render().
  */
 function _field_ui_reduce_order($array, $a) {
   $array = !isset($array) ? array() : $array;
@@ -91,8 +91,9 @@ function _field_ui_reduce_order($array, $a) {
 /**
  * Returns the region to which a row in the 'Manage fields' screen belongs.
  *
- * This function is used as a #row_callback in field_ui_field_overview_form(),
- * and is called during field_ui_table_pre_render().
+ * This function is used as a #region_callback in
+ * field_ui_field_overview_form(). It is called during
+ * field_ui_table_pre_render().
  */
 function field_ui_field_overview_row_region($row) {
   switch ($row['#row_type']) {
@@ -109,8 +110,9 @@ function field_ui_field_overview_row_region($row) {
 /**
  * Returns the region to which a row in the 'Manage display' screen belongs.
  *
- * This function is used as a #row_callback in field_ui_field_overview_form(),
- * and is called during field_ui_table_pre_render().
+ * This function is used as a #region_callback in
+ * field_ui_field_overview_form(), and is called during
+ * field_ui_table_pre_render().
  */
 function field_ui_display_overview_row_region($row) {
   switch ($row['#row_type']) {
@@ -274,9 +276,13 @@ function theme_field_ui_table($variables) {
 }
 
 /**
- * Menu callback; listing of fields for a bundle.
+ * Form constructor for the 'Manage fields' form of a bundle.
  *
  * Allows fields and pseudo-fields to be re-ordered.
+ *
+ * @see field_ui_overview_form_validate().
+ * @see field_ui_overview_form_submit().
+ * @ingroup forms
  */
 function field_ui_field_overview_form($form, &$form_state, $entity_type, $bundle) {
   $bundle = field_extract_bundle($entity_type, $bundle);
@@ -630,7 +636,9 @@ function field_ui_field_overview_form($form, &$form_state, $entity_type, $bundle
 }
 
 /**
- * Validate handler for the field overview form.
+ * Form validation handler for field_ui_field_overview_form().
+ *
+ * @see field_ui_field_overview_form_submit()
  */
 function field_ui_field_overview_form_validate($form, &$form_state) {
   _field_ui_field_overview_form_validate_add_new($form, $form_state);
@@ -638,9 +646,9 @@ function field_ui_field_overview_form_validate($form, &$form_state) {
 }
 
 /**
- * Helper function for field_ui_field_overview_form_validate.
+ * Validates the 'add new field' row of field_ui_field_overview_form().
  *
- * Validate the 'add new field' row.
+ * @see field_ui_field_overview_form_validate()
  */
 function _field_ui_field_overview_form_validate_add_new($form, &$form_state) {
   $field = $form_state['values']['fields']['_add_new_field'];
@@ -702,9 +710,9 @@ function _field_ui_field_overview_form_validate_add_new($form, &$form_state) {
 }
 
 /**
- * Helper function for field_ui_field_overview_form_validate.
+ * Validates the 'add existing field' row of field_ui_field_overview_form().
  *
- * Validate the 'add existing field' row.
+ * @see field_ui_field_overview_form_validate()
  */
 function _field_ui_field_overview_form_validate_add_existing($form, &$form_state) {
   // The form element might be absent if no existing fields can be added to
@@ -740,7 +748,9 @@ function _field_ui_field_overview_form_validate_add_existing($form, &$form_state
 }
 
 /**
- * Submit handler for the field overview form.
+ * Form submission handler for field_ui_field_overview_form().
+ *
+ * @see field_ui_field_overview_form_validate()
  */
 function field_ui_field_overview_form_submit($form, &$form_state) {
   $form_values = $form_state['values']['fields'];
@@ -846,7 +856,11 @@ function field_ui_field_overview_form_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; presents field display settings for a given view mode.
+ * Form constructor for the field display settings for a given view mode.
+ *
+ * @see field_ui_display_overview_multistep_submit()
+ * @see field_ui_display_overview_form_submit()
+ * @ingroup forms
  */
 function field_ui_display_overview_form($form, &$form_state, $entity_type, $bundle, $view_mode) {
   $bundle = field_extract_bundle($entity_type, $bundle);
@@ -1198,7 +1212,7 @@ function field_ui_display_overview_form($form, &$form_state, $entity_type, $bund
 
 
 /**
- * Form submit handler for multistep buttons on the 'Manage display' screen.
+ * Form submission handler for buttons in field_ui_display_overview_form().
  */
 function field_ui_display_overview_multistep_submit($form, &$form_state) {
   $trigger = $form_state['triggering_element'];
@@ -1244,7 +1258,7 @@ function field_ui_display_overview_multistep_js($form, &$form_state) {
   $trigger = $form_state['triggering_element'];
   $op = $trigger['#op'];
 
-  // Pick the elements that need ro receive the ajax-new-content effect.
+  // Pick the elements that need to receive the ajax-new-content effect.
   switch ($op) {
     case 'edit':
       $updated_rows = array($trigger['#field_name']);
@@ -1276,7 +1290,7 @@ function field_ui_display_overview_multistep_js($form, &$form_state) {
 }
 
 /**
- * Submit handler for the display overview form.
+ * Form submission handler for field_ui_display_overview_form().
  */
 function field_ui_display_overview_form_submit($form, &$form_state) {
   $form_values = $form_state['values'];
@@ -1354,7 +1368,7 @@ function field_ui_display_overview_form_submit($form, &$form_state) {
 }
 
 /**
- * Helper function for field_ui_display_overview_form_submit().
+ * Populates display settings for a new view mode from the default view mode.
  *
  * When an administrator decides to use custom display settings for a view mode,
  * that view mode needs to be initialized with the display settings for the
@@ -1363,8 +1377,6 @@ function field_ui_display_overview_form_submit($form, &$form_state) {
  * them. It also modifies the passed-in $settings array, which the caller can
  * then save using field_bundle_settings().
  *
- * @see field_bundle_settings()
- *
  * @param $entity_type
  *   The bundle's entity type.
  * @param $bundle
@@ -1374,6 +1386,9 @@ function field_ui_display_overview_form_submit($form, &$form_state) {
  * @param $settings
  *   An associative array of bundle settings, as expected by
  *   field_bundle_settings().
+ *
+ * @see field_ui_display_overview_form_submit().
+ * @see field_bundle_settings()
  */
 function _field_ui_add_default_view_mode_settings($entity_type, $bundle, $view_mode, &$settings) {
   // Update display settings for field instances.
@@ -1398,7 +1413,7 @@ function _field_ui_add_default_view_mode_settings($entity_type, $bundle, $view_m
 }
 
 /**
- * Return an array of field_type options.
+ * Returns an array of field_type options.
  */
 function field_ui_field_type_options() {
   $options = &drupal_static(__FUNCTION__);
@@ -1420,7 +1435,7 @@ function field_ui_field_type_options() {
 }
 
 /**
- * Return an array of widget type options for a field type.
+ * Returns an array of widget type options for a field type.
  *
  * If no field type is provided, returns a nested array of all widget types,
  * keyed by field type human name.
@@ -1456,7 +1471,7 @@ function field_ui_widget_type_options($field_type = NULL, $by_label = FALSE) {
 }
 
 /**
- * Return an array of formatter options for a field type.
+ * Returns an array of formatter options for a field type.
  *
  * If no field type is provided, returns a nested array of all formatters, keyed
  * by field type.
@@ -1484,7 +1499,7 @@ function field_ui_formatter_options($field_type = NULL) {
 }
 
 /**
- * Return an array of existing field to be added to a bundle.
+ * Returns an array of existing fields to be added to a bundle.
  */
 function field_ui_existing_field_options($entity_type, $bundle) {
   $options = array();
@@ -1522,7 +1537,10 @@ function field_ui_existing_field_options($entity_type, $bundle) {
 }
 
 /**
- * Menu callback; presents the field settings edit page.
+ * Form constructor for the field settings edit page.
+ *
+ * @see field_ui_settings_form_submit()
+ * @ingroups forms
  */
 function field_ui_field_settings_form($form, &$form_state, $instance) {
   $bundle = $instance['bundle'];
@@ -1576,7 +1594,7 @@ function field_ui_field_settings_form($form, &$form_state, $instance) {
 }
 
 /**
- * Save a field's settings after editing.
+ * Form submission handler for field_ui_field_settings_form().
  */
 function field_ui_field_settings_form_submit($form, &$form_state) {
   $form_values = $form_state['values'];
@@ -1603,7 +1621,15 @@ function field_ui_field_settings_form_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; select a widget for the field.
+ * Form constructor for the widget selection form.
+ *
+ * Path: BUNDLE_ADMIN_PATH/fields/%field/widget-type, where BUNDLE_ADMIN_PATH is
+ * the path stored in the ['admin']['info'] property in the return value of
+ * hook_entity_info().
+ *
+ * @see field_ui_menu()
+ * @see field_ui_widget_type_form_submit()
+ * @ingroup forms
  */
 function field_ui_widget_type_form($form, &$form_state, $instance) {
   drupal_set_title($instance['label']);
@@ -1647,7 +1673,7 @@ function field_ui_widget_type_form($form, &$form_state, $instance) {
 }
 
 /**
- * Submit the change in widget type.
+ * Form submission handler for field_ui_widget_type_form().
  */
 function field_ui_widget_type_form_submit($form, &$form_state) {
   $form_values = $form_state['values'];
@@ -1677,7 +1703,10 @@ function field_ui_widget_type_form_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; present a form for removing a field instance from a bundle.
+ * Form constructor for removing a field instance from a bundle.
+ *
+ * @see field_ui_delete_form_submit()
+ * @ingroup forms
  */
 function field_ui_field_delete_form($form, &$form_state, $instance) {
   $bundle = $instance['bundle'];
@@ -1707,9 +1736,10 @@ function field_ui_field_delete_form($form, &$form_state, $instance) {
 }
 
 /**
- * Removes a field instance from a bundle.
+ * Form submission handler for field_ui_field_delete_form().
  *
- * If the field has no more instances, it will be marked as deleted too.
+ * Removes a field instance from a bundle. If the field has no more instances,
+ * it will be marked as deleted too.
  */
 function field_ui_field_delete_form_submit($form, &$form_state) {
   $form_values = $form_state['values'];
@@ -1743,7 +1773,11 @@ function field_ui_field_delete_form_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; presents the field instance edit page.
+ * Form constructor for the field instance settings form.
+ *
+ * @see field_ui_field_edit_form_validate()
+ * @see field_ui_field_edit_form_submit()
+ * @ingroup forms
  */
 function field_ui_field_edit_form($form, &$form_state, $instance) {
   $bundle = $instance['bundle'];
@@ -1924,7 +1958,7 @@ function field_ui_field_edit_instance_pre_render($element) {
 }
 
 /**
- * Build default value fieldset.
+ * Builds the default value fieldset for a given field instance.
  */
 function field_ui_default_value_widget($field, $instance, &$form, &$form_state) {
   $field_name = $field['field_name'];
@@ -1953,7 +1987,9 @@ function field_ui_default_value_widget($field, $instance, &$form, &$form_state)
 }
 
 /**
- * Form validation handler for field instance settings form.
+ * Form validation handler for field_ui_field_edit_form().
+ *
+ * @see field_ui_field_edit_form_submit().
  */
 function field_ui_field_edit_form_validate($form, &$form_state) {
   // Take the incoming values as the $instance definition, so that the 'default
@@ -1988,7 +2024,9 @@ function field_ui_field_edit_form_validate($form, &$form_state) {
 }
 
 /**
- * Form submit handler for field instance settings form.
+ * Form submission handler for field_ui_field_edit_form().
+ *
+ * @see field_ui_field_edit_form_validate().
  */
 function field_ui_field_edit_form_submit($form, &$form_state) {
   $instance = $form_state['values']['instance'];
@@ -2028,7 +2066,9 @@ function field_ui_field_edit_form_submit($form, &$form_state) {
 }
 
 /**
- * Helper functions to handle multipage redirects.
+ * Extracts next redirect path from an array of multiple destinations.
+ *
+ * @see field_ui_next_destination()
  */
 function field_ui_get_destinations($destinations) {
   $path = array_shift($destinations);
@@ -2040,7 +2080,7 @@ function field_ui_get_destinations($destinations) {
 }
 
 /**
- * Return the next redirect path in a multipage sequence.
+ * Returns the next redirect path in a multipage sequence.
  */
 function field_ui_next_destination($entity_type, $bundle) {
   $destinations = !empty($_REQUEST['destinations']) ? $_REQUEST['destinations'] : array();
diff --git a/modules/field_ui/field_ui.api.php b/modules/field_ui/field_ui.api.php
index 234012512..f903e12f3 100644
--- a/modules/field_ui/field_ui.api.php
+++ b/modules/field_ui/field_ui.api.php
@@ -132,7 +132,7 @@ function hook_field_widget_settings_form($field, $instance) {
 
 
 /**
- * Returns form elements for a formatter's settings.
+ * Specify the form elements for a formatter's settings.
  *
  * @param $field
  *   The field structure being configured.
@@ -170,7 +170,7 @@ function hook_field_formatter_settings_form($field, $instance, $view_mode, $form
 }
 
 /**
- * Returns a short summary for the current formatter settings of an instance.
+ * Return a short summary for the current formatter settings of an instance.
  *
  * If an empty result is returned, the formatter is assumed to have no
  * configurable settings, and no UI will be provided to display a settings
diff --git a/modules/field_ui/field_ui.css b/modules/field_ui/field_ui.css
index c25d2a436..ae469e207 100644
--- a/modules/field_ui/field_ui.css
+++ b/modules/field_ui/field_ui.css
@@ -1,4 +1,8 @@
-
+/**
+ * @file
+ * Stylesheet for the Field UI module.
+ */
+ 
 /* 'Manage fields' and 'Manage display' overviews */
 table.field-ui-overview tr.add-new .label-input {
   float: left; /* LTR */
diff --git a/modules/field_ui/field_ui.js b/modules/field_ui/field_ui.js
index b63399f3d..0e2b9ae54 100644
--- a/modules/field_ui/field_ui.js
+++ b/modules/field_ui/field_ui.js
@@ -1,4 +1,8 @@
-
+/**
+ * @file
+ * Attaches the behaviors for the Field UI module.
+ */
+ 
 (function($) {
 
 Drupal.behaviors.fieldUIFieldOverview = {
diff --git a/modules/field_ui/field_ui.module b/modules/field_ui/field_ui.module
index 3be23c889..b8b80db96 100644
--- a/modules/field_ui/field_ui.module
+++ b/modules/field_ui/field_ui.module
@@ -1,8 +1,7 @@
 <?php
-
 /**
  * @file
- * Allows administrators to associate custom fields to fieldable types.
+ * Allows administrators to attach custom fields to fieldable types.
  */
 
 /**
@@ -213,6 +212,11 @@ function field_ui_menu() {
  *   The position of $bundle_name in $map.
  * @param $map
  *   The translated menu router path argument map.
+ *
+ * @return
+ *   The field instance array.
+ *
+ * @ingroup field
  */
 function field_ui_menu_load($field_name, $entity_type, $bundle_name, $bundle_pos, $map) {
   // Extract the actual bundle name from the translated argument map.
@@ -313,7 +317,7 @@ function field_ui_field_attach_create_bundle($entity_type, $bundle) {
 }
 
 /**
- * Helper function to create the right administration path for a bundle.
+ * Determines the adminstration path for a bundle.
  */
 function _field_ui_bundle_admin_path($entity_type, $bundle_name) {
   $bundles = field_info_bundles($entity_type);
@@ -324,7 +328,7 @@ function _field_ui_bundle_admin_path($entity_type, $bundle_name) {
 }
 
 /**
- * Helper function to identify inactive fields within a bundle.
+ * Identifies inactive fields within a bundle.
  */
 function field_ui_inactive_instances($entity_type, $bundle_name = NULL) {
   if (!empty($bundle_name)) {
@@ -351,7 +355,12 @@ function field_ui_inactive_instances($entity_type, $bundle_name = NULL) {
 }
 
 /**
- * Add a button Save and add fields to Create content type form.
+ * Implements hook_form_FORM_ID_alter().
+ *
+ * Adds a button 'Save and add fields' to the 'Create content type' form.
+ *
+ * @see node_type_form()
+ * @see field_ui_form_node_type_form_submit()
  */
 function field_ui_form_node_type_form_alter(&$form, $form_state) {
   // We want to display the button only on add page.
@@ -366,7 +375,9 @@ function field_ui_form_node_type_form_alter(&$form, $form_state) {
 }
 
 /**
- * Redirect to manage fields form.
+ * Form submission handler for the 'Save and add fields' button.
+ *
+ * @see field_ui_form_node_type_form_alter()
  */
 function field_ui_form_node_type_form_submit($form, &$form_state) {
   if ($form_state['triggering_element']['#parents'][0] === 'save_continue') {
diff --git a/modules/field_ui/field_ui.test b/modules/field_ui/field_ui.test
index ea8727e5b..f1e770baa 100644
--- a/modules/field_ui/field_ui.test
+++ b/modules/field_ui/field_ui.test
@@ -6,7 +6,7 @@
  */
 
 /**
- * Helper class for Field UI test classes.
+ * Provides common functionality for the Field UI test classes.
  */
 class FieldUITestCase extends DrupalWebTestCase {
 
@@ -34,10 +34,10 @@ class FieldUITestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Create a new field through the Field UI.
+   * Creates a new field through the Field UI.
    *
    * @param $bundle_path
-   *   Path of the 'Manage fields' page for the bundle.
+   *   Admin path of the bundle that the new field is to be attached to.
    * @param $initial_edit
    *   $edit parameter for drupalPost() on the first step ('Manage fields'
    *   screen).
@@ -74,10 +74,10 @@ class FieldUITestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Add an existing field through the Field UI.
+   * Adds an existing field through the Field UI.
    *
    * @param $bundle_path
-   *   Path of the 'Manage fields' page for the bundle.
+   *   Admin path of the bundle that the field is to be attached to.
    * @param $initial_edit
    *   $edit parameter for drupalPost() on the first step ('Manage fields'
    *   screen).
@@ -105,10 +105,10 @@ class FieldUITestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Delete a field instance through the Field UI.
+   * Deletes a field instance through the Field UI.
    *
    * @param $bundle_path
-   *   Path of the 'Manage fields' page for the bundle.
+   *   Admin path of the bundle that the field instance is to be deleted from.
    * @param $field_name
    *   The name of the field.
    * @param $label
@@ -131,7 +131,7 @@ class FieldUITestCase extends DrupalWebTestCase {
 }
 
 /**
- * Field UI tests for the 'Manage fields' screen.
+ * Tests the functionality of the 'Manage fields' screen.
  */
 class FieldUIManageFieldsTestCase extends FieldUITestCase {
   public static function getInfo() {
@@ -152,7 +152,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
   }
 
   /**
-   * Main entry point for the field CRUD tests.
+   * Runs the field CRUD tests.
    *
    * In order to act on the same fields, and not create the fields over and over
    * again the following tests create, update and delete the same fields.
@@ -165,7 +165,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
   }
 
   /**
-   * Test the manage fields page.
+   * Tests the manage fields page.
    */
   function manageFieldsPage() {
     $this->drupalGet('admin/structure/types/manage/' . $this->hyphen_type . '/fields');
@@ -190,7 +190,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
   }
 
   /**
-   * Test adding a new field.
+   * Tests adding a new field.
    *
    * @todo Assert properties can bet set in the form and read back in $field and
    * $instances.
@@ -212,7 +212,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
   }
 
   /**
-   * Test editing an existing field.
+   * Tests editing an existing field.
    */
   function updateField() {
     // Go to the field edit page.
@@ -235,7 +235,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
   }
 
   /**
-   * Test adding an existing field in another content type.
+   * Tests adding an existing field in another content type.
    */
   function addExistingField() {
     // Check "Add existing field" appears.
@@ -256,7 +256,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
   }
 
   /**
-   * Assert the field settings.
+   * Asserts field settings are as expected.
    *
    * @param $bundle
    *   The bundle name for the instance.
@@ -378,7 +378,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
   }
 
   /**
-   * Test that Field UI respects the 'no_ui' option in hook_field_info().
+   * Tests that Field UI respects the 'no_ui' option in hook_field_info().
    */
   function testHiddenFields() {
     $bundle_path = 'admin/structure/types/manage/' . $this->hyphen_type . '/fields/';
@@ -429,7 +429,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
 }
 
 /**
- * Field UI tests for the 'Manage display' screens.
+ * Tests the functionality of the 'Manage display' screens.
  */
 class FieldUIManageDisplayTestCase extends FieldUITestCase {
   public static function getInfo() {
@@ -445,7 +445,7 @@ class FieldUIManageDisplayTestCase extends FieldUITestCase {
   }
 
   /**
-   * Test formatter formatter settings.
+   * Tests formatter settings.
    */
   function testFormatterUI() {
     $manage_fields = 'admin/structure/types/manage/' . $this->hyphen_type;
@@ -493,7 +493,7 @@ class FieldUIManageDisplayTestCase extends FieldUITestCase {
   }
 
   /**
-   * Test switching view modes to use custom or 'default' settings'.
+   * Tests switching view modes to use custom or 'default' settings'.
    */
   function testViewModeCustom() {
     // Create a field, and a node with some data for the field.
@@ -565,7 +565,7 @@ class FieldUIManageDisplayTestCase extends FieldUITestCase {
   }
 
   /**
-   * Pass if the text is found in the rendered node in a given view mode.
+   * Asserts that a string is found in the rendered node in a view mode.
    *
    * @param $node
    *   The node.
@@ -584,7 +584,7 @@ class FieldUIManageDisplayTestCase extends FieldUITestCase {
   }
 
   /**
-   * Pass if the text is node found in the rendered node in a given view mode.
+   * Asserts that a string is not found in the rendered node in a view mode.
    *
    * @param $node
    *   The node.
@@ -602,7 +602,10 @@ class FieldUIManageDisplayTestCase extends FieldUITestCase {
   }
 
   /**
-   * Helper for assertNodeViewText and assertNodeViewNoText.
+   * Asserts that a string is (not) found in the rendered nodein a view mode.
+   *
+   * This helper function is used by assertNodeViewText() and
+   * assertNodeViewNoText().
    *
    * @param $node
    *   The node.