Issue #1326638 by sven.lauer, jhodgdon, xjm: Clean up API docs for fi…

…eld_ui() module.

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 {

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,17 +636,19 @@ 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);
   _field_ui_field_overview_form_validate_add_existing($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();

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

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 */

modules/field_ui/field_ui.js

@@ -1,4 +1,8 @@
-
+/**
+ * @file
+ * Attaches the behaviors for the Field UI module.
+ */
+
 (function($) {
 
 Drupal.behaviors.fieldUIFieldOverview = {