Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.80
diff -u -r1.80 system.api.php
--- modules/system/system.api.php	1 Oct 2009 13:16:17 -0000	1.80
+++ modules/system/system.api.php	8 Oct 2009 17:45:16 -0000
@@ -24,18 +24,17 @@
  * @return
  *   An array whose keys are entity type names and whose values identify
  *   properties of those types that the  system needs to know about:
- *
- *   name: The human-readable name of the type.
- *   controller class: The name of the class that is used to load the objects.
+ *   - name: The human-readable name of the type.
+ *   - controller class: The name of the class that is used to load the objects.
  *     The class has to implement the DrupalEntityController interface. Leave
  *     blank to use the DefaultDrupalEntityController implementation.
- *   base table: (used by DefaultDrupalEntityController) The name of the entity
- *     type's base table.
- *   static cache: (used by DefaultDrupalEntityController) FALSE to disable
+ *   - base table: (used by DefaultDrupalEntityController) The name of the
+ *     entity type's base table.
+ *   - static cache: (used by DefaultDrupalEntityController) FALSE to disable
  *     static caching of entities during a page request. Defaults to TRUE.
- *   load hook: The name of the hook which should be invoked by
- *   DrupalDefaultEntityController:attachLoad(), for example 'node_load'.
- *   fieldable: Set to TRUE if you want your entity type to be fieldable.
+ *   - load hook: The name of the hook which should be invoked by
+ *     DrupalDefaultEntityController:attachLoad(), for example 'node_load'.
+ *   - fieldable: Set to TRUE if you want your entity type to be fieldable.
  *   - object keys: An array describing how the Field API can extract the
  *     information it needs from the objects of the type.
  *     - id: The name of the property that contains the primary id of the
@@ -55,7 +54,7 @@
  *     information it needs from the bundle objects for this type (e.g
  *     $vocabulary objects for terms; not applicable for nodes).
  *     This element can be omitted if this type's bundles do not exist as
- *     standalone objects.
+ *     standalone objects. Array components:
  *     - bundle: The name of the property that contains the name of the bundle
  *       object.
  *   - cacheable: A boolean indicating whether Field API should cache
@@ -63,7 +62,8 @@
  *     field_attach_load().
  *   - bundles: An array describing all bundles for this object type.
  *     Keys are bundles machine names, as found in the objects' 'bundle'
- *     property (defined in the 'object keys' entry above).
+ *     property (defined in the 'object keys' entry above). Each element has
+ *     the following components:
  *     - label: The human-readable name of the bundle.
  *     - admin: An array of information that allow Field UI pages (currently
  *       implemented in a contributed module) to attach themselves to the
@@ -88,7 +88,7 @@
       'id key' => 'nid',
       'revision key' => 'vid',
       'fieldable' => TRUE,
-      'bundle key' => 'type',
+      'bundle key' => array('bundle' => 'type'),
       // Node.module handles its own caching.
       // 'cacheable' => FALSE,
       // Bundles must provide human readable name so
Index: modules/field/field.info.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.info.inc,v
retrieving revision 1.19
diff -u -r1.19 field.info.inc
--- modules/field/field.info.inc	27 Sep 2009 12:52:55 -0000	1.19
+++ modules/field/field.info.inc	8 Oct 2009 17:45:16 -0000
@@ -17,7 +17,7 @@
  */
 
 /**
- * Clear the field info cache without clearing the field data cache.
+ * Clears the field info cache without clearing the field data cache.
  *
  * This is useful when deleted fields or instances are purged.  We
  * need to remove the purged records, but no actual field data items
@@ -30,39 +30,42 @@
 }
 
 /**
- * Collate all information on field types, widget types and related structures.
+ * Collates all information on field types, widget types and related structures.
  *
  * @param $reset
  *   If TRUE, clear the cache. The information will be rebuilt from the database
  *   next time it is needed. Defaults to FALSE.
+ *
  * @return
  *   If $reset is TRUE, nothing.
  *   If $reset is FALSE, an array containing the following elements:
- *
- * field types: array of hook_field_info() results, keyed by field_type.
- *   * label, description, settings, instance_settings, default_widget,
- *     default_formatter, behaviors: from hook_field_info()
- *   * module: the module that exposes the field type
- *
- * widget types: array of hook_field_widget_info() results, keyed by
- * widget_type.
- *   * label, field types, settings, behaviors: from hook_field_widget_info()
- *   * module: module that exposes the widget type
- *
- * formatter types: array of hook_field_formatter_info() results, keyed by
- * formatter_type.
- *   * label, field types, behaviors: from hook_field_formatter_info()
- *   * module: module that exposes the formatter type
-
- * fieldable types: array of hook_entity_info() results, keyed by entity_type.
- *   * name, id key, revision key, bundle key, cacheable, bundles: from
- *     hook_entity_info()
- *   * module: module that exposes the entity type
- * @TODO use entity_get_info().
+ *   - 'field types': Array of hook_field_info() results, keyed by field_type.
+ *     Each element has the following components: label, description, settings,
+ *     instance_settings, default_widget, default_formatter, and behaviors
+ *     from hook_field_info(), as well as module, giving the module that exposes
+ *     the field type.
+ *   - 'widget types': Array of hook_field_widget_info() results, keyed by
+ *     widget_type. Each element has the following components: label, field
+ *     types, settings, and behaviors from hook_field_widget_info(), as well
+ *     as module, giving the module that exposes the widget type.
+ *   - 'formatter types': Array of hook_field_formatter_info() results, keyed by
+ *     formatter_type. Each element has the following components: label, field
+ *     types, and behaviors from hook_field_formatter_info(), as well as
+ *     module, giving the module that exposes the formatter type.
+ *   - 'storage types': Array of hook_field_storage_info() results, keyed by
+ *     storage type names. Each element has the following components: label,
+ *     description, and settings from hook_field_storage_info(), as well as
+ *     module, giving the module that exposes the storage type.
+ *   - 'fieldable types': Array of hook_entity_info() results, keyed by
+ *     entity_type. Each element has the following components: name, id key,
+ *     revision key, bundle key, cacheable, and bundles from hook_entity_info(),
+ *     as well as module, giving the module that exposes the entity type.
  */
 function _field_info_collate_types($reset = FALSE) {
   static $info;
 
+  // @TODO use entity_get_info().
+
   if ($reset) {
     $info = NULL;
     cache_clear_all('field_info_types', 'cache_field');
@@ -175,11 +178,12 @@
 }
 
 /**
- * Collate all information on existing fields and instances.
+ * Collates all information on existing fields and instances.
  *
  * @param $reset
  *   If TRUE, clear the cache. The information will be rebuilt from the
  *   database next time it is needed. Defaults to FALSE.
+ *
  * @return
  *   If $reset is TRUE, nothing.
  *   If $reset is FALSE, an array containing the following elements:
@@ -249,8 +253,8 @@
   return $info;
 }
 
- /**
- * Prepare a field definition for the current run-time context.
+/**
+ * Prepares a field definition for the current run-time context.
  *
  * Since the field was last saved or updated, new field settings can be
  * expected.
@@ -267,7 +271,7 @@
 }
 
 /**
- * Prepare an instance definition for the current run-time context.
+ * Prepares an instance definition for the current run-time context.
  *
  * Since the instance was last saved or updated, a number of things might have
  * changed: widgets or formatters disabled, new settings expected, new build
@@ -277,6 +281,9 @@
  *   The raw instance structure as read from the database.
  * @param $field
  *   The field structure for the instance.
+ *
+ * @return
+ *   Field instance array.
  */
 function _field_info_prepare_instance($instance, $field) {
   $field_type = field_info_field_types($field['type']);
@@ -319,18 +326,19 @@
 }
 
 /**
- *  Helper function for determining the behavior of a widget
- *  with respect to a given operation.
+ * Determines the behavior of a widget with respect to an operation.
  *
- *  @param $op
- *    The name of the operation.
- *    Currently supported: 'default value', 'multiple values'.
- *  @param $instance
- *    The field instance array.
- *  @return
- *    FIELD_BEHAVIOR_NONE    - do nothing for this operation.
- *    FIELD_BEHAVIOR_CUSTOM  - use the widget's callback function.
- *    FIELD_BEHAVIOR_DEFAULT - use field.module default behavior.
+ * @param $op
+ *   The name of the operation. Currently supported: 'default value',
+ *   'multiple values'.
+ * @param $instance
+ *   The field instance array.
+ *
+ * @return
+ *   One of these values:
+ *   - FIELD_BEHAVIOR_NONE: Do nothing for this operation.
+ *   - FIELD_BEHAVIOR_CUSTOM: Use the widget's callback function.
+ *   - FIELD_BEHAVIOR_DEFAULT: Use field.module default behavior.
  */
 function field_behaviors_widget($op, $instance) {
   $info = field_info_widget_types($instance['widget']['type']);
@@ -338,18 +346,18 @@
 }
 
 /**
- *  Helper function for determining the behavior of a formatter
- *  with respect to a given operation.
+ * Determines the behavior of a formatter with respect to an operation.
  *
  *  @param $op
- *    The name of the operation.
- *    Currently supported: 'multiple values'
+ *    The name of the operation. Currently supported: 'multiple values'.
  *  @param $display
  *    The $instance['display'][$build_mode] array.
+ *
  *  @return
- *    FIELD_BEHAVIOR_NONE    - do nothing for this operation.
- *    FIELD_BEHAVIOR_CUSTOM  - use the formatter's callback function.
- *    FIELD_BEHAVIOR_DEFAULT - use field module default behavior.
+ *    One of these values:
+ *    - FIELD_BEHAVIOR_NONE: Do nothing for this operation.
+ *    - FIELD_BEHAVIOR_CUSTOM: Use the formatter's callback function.
+ *    - FIELD_BEHAVIOR_DEFAULT: Use field module default behavior.
  */
 function field_behaviors_formatter($op, $display) {
   $info = field_info_formatter_types($display['type']);
@@ -357,11 +365,12 @@
 }
 
 /**
- * Return hook_field_info() data.
+ * Returns information about field types from hook_field_info().
  *
  * @param $field_type
  *   (optional) A field type name. If ommitted, all field types will be
  *   returned.
+ *
  * @return
  *   Either a field type description, as provided by hook_field_info(), or an
  *   array of all existing field types, keyed by field type name.
@@ -380,13 +389,14 @@
 }
 
 /**
- * Return hook_field_widget_info() data.
+ * Returns information about field widgets from hook_field_widget_info().
  *
  * @param $widget_type
  *   (optional) A widget type name. If ommitted, all widget types will be
  *   returned.
+ *
  * @return
- *   Either a widget type description, as provided by
+ *   Either a single widget type description, as provided by
  *   hook_field_widget_info(), or an array of all existing widget types, keyed
  *   by widget type name.
  */
@@ -404,13 +414,14 @@
 }
 
 /**
- * Return hook_field_formatter_info() data.
+ * Returns information about field formatters from hook_field_formatter_info().
  *
  * @param $formatter_type
  *   (optional) A formatter type name. If ommitted, all formatter types will be
  *   returned.
+ *
  * @return
- *   Either a formatter type description, as provided by
+ *   Either a single formatter type description, as provided by
  *   hook_field_formatter_info(), or an array of all existing formatter types,
  *   keyed by formatter type name.
  */
@@ -428,11 +439,12 @@
 }
 
 /**
- * Return hook_field_storage_info() data.
+ * Returns information abotu field storage from hook_field_storage_info().
  *
  * @param $storage_type
  *   (optional) A storage type name. If ommitted, all storage types will be
  *   returned.
+ *
  * @return
  *   Either a storage type description, as provided by
  *   hook_field_storage_info(), or an array of all existing storage types,
@@ -452,14 +464,22 @@
 }
 
 /**
- * Return hook_fieldable_info() data.
+ * Returns information about a fieldable type or multiple types.
+ *
+ * Types (also known as entity types) can define themselves to be fieldable by
+ * setting 'fieldable' to TRUE in their hook_entity_info() return values.
  *
  * @param $obj_type
  *   (optional) A fieldable type name. If ommitted, all fieldable types will be
  *   returned.
+ *
  * @return
- *   Either a fieldable type description, as provided by hook_fieldable_info(),
- *   or an array of all existing fieldable types, keyed by fieldable type name.
+ *   If $obj_type is provided, a single entity description (if that type has
+ *   been defined); if $obj_type is omitted, an associative array of all entity
+ *   descriptions, keyed by entity type name. Entity descriptions
+ *   are the return values of hook_entity_info(), with an additional component
+ *   'module' added to each description, telling what module the description
+ *   came from.
  */
 function field_info_fieldable_types($obj_type = NULL) {
   $info = _field_info_collate_types();
@@ -475,8 +495,16 @@
 }
 
 /**
- * Return an array of fieldable bundle names and labels, for an individual
- * object type or for all object types.
+ * Returns information on bundles from hook_entity_info().
+ *
+ * @param $obj_type
+ *   (optional) A fieldable type name. If ommitted, bundle information from
+ *   all fieldable types will be returned.
+ * 
+ * @return
+ *   The 'bundles' component of hook_entity_info() return values for a
+ *   single fieldable entity type, or an array of all bundle information
+ *   keyed by type name.
  */
 function field_info_bundles($obj_type = NULL) {
   $info = _field_info_collate_types();
@@ -490,7 +518,7 @@
 }
 
 /**
- * Identify the type of entity that created a bundle.
+ * Identifies and returns the type of entity that created a bundle.
  * // TODO : might not be needed depending on how we solve
  * // the 'namespace bundle names' issue
  */
@@ -505,12 +533,12 @@
 }
 
 /**
- * Return array of all field data, keyed by field name.
+ * Returns an array of all field data, keyed by field name.
  *
  * @return
- *   An array of Field objects. Each Field object has an additional
- *   property, bundles, which is an array of all the bundles to which
- *   this field belongs.
+ *   An array of field arrays, as returned by field_read_fields(), with an
+ *   additional element 'bundles', whose value is an array of all the bundles
+ *   this field belongs to.
  */
 function field_info_fields() {
   $info = _field_info_collate_fields();
@@ -518,15 +546,18 @@
 }
 
 /**
- * Return data about an individual field.
+ * Returns data about an individual field, given a field name.
  *
  * @param $field_name
  *   The name of the field to retrieve. $field_name can only refer to a
  *   non-deleted field.
+ *
  * @return
- *   The named field object, or NULL. The Field object has an additional
- *   property, bundles, which is an array of all the bundles to which
- *   this field belongs.
+ *   The field array, as returned by field_read_fields(), with an
+ *   additional element 'bundles', whose value is an array of all the bundles
+ *   this field belongs to.
+ *
+ * @see field_info_field_by_id().
  */
 function field_info_field($field_name) {
   $info = _field_info_collate_fields();
@@ -536,15 +567,18 @@
 }
 
 /**
- * Return data about an individual field by its id.
+ * Returns data about an individual field, given a field ID.
  *
  * @param $field_id
  *   The id of the field to retrieve. $field_id can refer to a
  *   deleted field.
+ *
  * @return
- *   The named field object, or NULL. The Field object has an additional
- *   property, bundles, which is an array of all the bundles to which
- *   this field belongs.
+ *   The field array, as returned by field_read_fields(), with an
+ *   additional element 'bundles', whose value is an array of all the bundles
+ *   this field belongs to.
+ *
+ * @see field_info_field().
  */
 function field_info_field_by_id($field_id) {
   $info = _field_info_collate_fields();
@@ -554,11 +588,15 @@
 }
 
 /**
- * Return an array of instance data for a given bundle,
- * or for all known bundles, keyed by bundle name and field name.
+ * Returns information about instances of a bundle or all bundles.
  *
  * @param $bundle_name
- *   If set, return information on just this bundle.
+ *   If set, return information on just this bundle. Otherwise, return all
+ *   bundle information.
+ *
+ * @return
+ *   Array of instance data for the given bundle, or for all known bundles,
+ *   keyed by bundle name and field name.
  */
 function field_info_instances($bundle_name = NULL) {
   $info = _field_info_collate_fields();
@@ -572,7 +610,7 @@
 }
 
 /**
- * Return an array of instance data for a specific field and bundle.
+ * Returns an array of instance data for a specific field and bundle.
  */
 function field_info_instance($field_name, $bundle_name) {
   $info = _field_info_collate_fields();
@@ -582,13 +620,14 @@
 }
 
 /**
- * Return a field type's default settings.
+ * Returns a field type's default settings.
  *
  * @param $type
  *   A field type name.
+ *
  * @return
  *   The field type's default settings, as provided by hook_field_info(), or an
- *   empty array.
+ *   empty array if type or settings are not defined.
  */
 function field_info_field_settings($type) {
   $info = field_info_field_types($type);
@@ -596,13 +635,14 @@
 }
 
 /**
- * Return a field type's default instance settings.
+ * Returns a field type's default instance settings.
  *
  * @param $type
  *   A field type name.
+ *
  * @return
  *   The field type's default instance settings, as provided by
- *   hook_field_info(), or an empty array.
+ *   hook_field_info(), or an empty array if type or settings are not defined.
  */
 function field_info_instance_settings($type) {
   $info = field_info_field_types($type);
@@ -610,13 +650,15 @@
 }
 
 /**
- * Return a field widget's default settings.
+ * Returns a field widget's default settings.
  *
  * @param $type
  *   A widget type name.
+ *
  * @return
  *   The widget type's default settings, as provided by
- *   hook_field_widget_info(), or an empty array.
+ *   hook_field_widget_info(), or an empty array if type or settings are
+ *   undefined.
  */
 function field_info_widget_settings($type) {
   $info = field_info_widget_types($type);
@@ -624,13 +666,15 @@
 }
 
 /**
- * Return a field formatter's default settings.
+ * Returns a field formatter's default settings.
  *
  * @param $type
  *   A field formatter type name.
+ *
  * @return
  *   The formatter type's default settings, as provided by
- *   hook_field_formatter_info(), or an empty array.
+ *   hook_field_formatter_info(), or an empty array if type or settings are
+ *   undefined.
  */
 function field_info_formatter_settings($type) {
   $info = field_info_formatter_types($type);
@@ -638,13 +682,15 @@
 }
 
 /**
- * Return a field formatter's default settings.
+ * Returns a field storage type's default settings.
  *
  * @param $type
  *   A field storage type name.
+ *
  * @return
  *   The storage type's default settings, as provided by
- *   hook_field_storage_info(), or an empty array.
+ *   hook_field_storage_info(), or an empty array if type or settings are
+ *   undefined.
  */
 function field_info_storage_settings($type) {
   $info = field_info_storage_types($type);