Issue #1454266 by Chaulky, Volx: fix documentation for field_bundle_settings

1 files changed, 24 insertions, 42 deletions

diff --git a/modules/field/field.module b/modules/field/field.module
index 127213734..671fc0ad1 100644
--- a/modules/field/field.module
+++ b/modules/field/field.module
@@ -555,51 +555,33 @@ function _field_sort_items_value_helper($a, $b) {
 /**
  * Gets or sets administratively defined bundle settings.
  *
- * For each bundle, settings are provided as a nested array with the following
- * structure:
- * @code
- * array(
- *   'view_modes' => array(
- *     // One sub-array per view mode for the entity type:
- *     'full' => array(
- *       'custom_display' => Whether the view mode uses custom display
- *         settings or settings of the 'default' mode,
- *     ),
- *     'teaser' => ...
- *   ),
- *   'extra_fields' => array(
- *     'form' => array(
- *       // One sub-array per pseudo-field in displayed entities:
- *       'extra_field_1' => array(
- *         'weight' => The weight of the pseudo-field,
- *       ),
- *       'extra_field_2' => ...
- *     ),
- *     'display' => array(
- *       // One sub-array per pseudo-field in displayed entities:
- *       'extra_field_1' => array(
- *         // One sub-array per view mode for the entity type, including
- *         // the 'default' mode:
- *         'default' => array(
- *           'weight' => The weight of the pseudo-field,
- *           'visible' => TRUE if the pseudo-field is visible, FALSE if hidden,
- *         ),
- *         'full' => ...
- *       ),
- *       'extra_field_2' => ...
- *     ),
- *   ),
- * );
- * @endcode
- *
- * @param $entity_type
+ * @param string $entity_type
  *   The type of $entity; e.g., 'node' or 'user'.
- * @param $bundle
+ * @param string $bundle
  *   The bundle name.
- * @param $settings
- *   (optional) The settings to store.
+ * @param array|null $settings
+ *   (optional) The settings to store, an associative array with the following
+ *   elements:
+ *   - view_modes: An associative array keyed by view mode, with the following
+ *     key/value pairs:
+ *     - custom_settings: Boolean specifying whether the view mode uses a
+ *       dedicated set of display options (TRUE), or the 'default' options
+ *       (FALSE). Defaults to FALSE.
+ *   - extra_fields: An associative array containing the form and display
+ *     settings for extra fields (also known as pseudo-fields):
+ *     - form: An associative array whose keys are the names of extra fields,
+ *       and whose values are associative arrays with the following elements:
+ *       - weight: The weight of the extra field, determining its position on an
+ *         entity form.
+ *     - display: An associative array whose keys are the names of extra fields,
+ *       and whose values are associative arrays keyed by the name of view
+ *       modes. This array must include an item for the 'default' view mode.
+ *       Each view mode sub-array contains the following elements:
+ *       - weight: The weight of the extra field, determining its position when
+ *         an entity is viewed.
+ *       - visible: TRUE if the extra field is visible, FALSE otherwise.
  *
- * @return
+ * @return array|null
  *   If no $settings are passed, the current settings are returned.
  */
 function field_bundle_settings($entity_type, $bundle, $settings = NULL) {