#664136 by plach, sun, yched: Enhance TF code documentation.

2 files changed, 62 insertions, 1 deletions

diff --git a/modules/field/field.multilingual.inc b/modules/field/field.multilingual.inc
index 600ed3010..32eb6a98f 100644
--- a/modules/field/field.multilingual.inc
+++ b/modules/field/field.multilingual.inc
@@ -3,7 +3,61 @@
 
 /**
  * @file
- * Multilingual field API helper functions.
+ * Functions implementing Field API multilingual support.
+ */
+
+/**
+ * @defgroup field_language Field language API
+ * @{
+ * Handling of multilingual fields.
+ *
+ * Fields natively implement multilingual support, and all fields use the
+ * following structure:
+ * @code
+ * $entity->{$field_name}[$langcode][$delta][$column_name]
+ * @endcode
+ * Every field can hold a single or multiple value for each language belonging
+ * to the available languages set:
+ * - For untranslatable fields this set only contains LANGUAGE_NONE.
+ * - For translatable fields this set can contain any language code. By default
+ *   it is the list returned by field_content_languages(), which contains all
+ *   enabled languages with the addition of LANGUAGE_NONE. This default can be
+ *   altered by modules implementing hook_field_available_languages_alter().
+ *
+ * The available languages for a particular field are returned by
+ * field_available_languages(). Whether a field is translatable is determined by
+ * calling field_is_translatable(), which checks the $field['translatable']
+ * property returned by field_info_field(), and whether there is at least one
+ * translation handler available for the field. A translation handler is a
+ * module registering itself via hook_entity_info() to handle field
+ * translations.
+ *
+ * By default, _field_invoke() and _field_invoke_multiple() are processing a
+ * field in all available languages, unless they are given a language
+ * suggestion. Based on that suggestion, _field_language_suggestion() determines
+ * the languages to act on.
+ *
+ * Most field_attach_*() functions act on all available languages, except for
+ * the following:
+ * - field_attach_form() only takes a single language code, specifying which
+ *   language the field values will be submitted in.
+ * - field_attach_view() requires the language the entity will be displayed in.
+ *   Since it is unknown whether a field translation exists for the requested
+ *   language, the translation handler is responsible for performing one of the
+ *   following actions:
+ *   - Ignore missing translations, i.e. do not show any field values for the
+ *     requested language. For example, see locale_field_language_alter().
+ *   - Provide a value in a different language as fallback. By default, the
+ *     fallback logic is applied separately to each field to ensure that there
+ *     is a value for each field to display.
+ *   The field language fallback logic relies on the global language fallback
+ *   configuration. Therefore, the displayed field values can be in the
+ *   requested language, but may be different if no values for the requested
+ *   language are available. The default language fallback rules inspect all the
+ *   enabled languages ordered by their weight. This behavior can be altered or
+ *   even disabled by modules implementing hook_field_language_alter(), making
+ *   it possible to choose the first approach. The display language for each
+ *   field is returned by field_language().
  */
 
 /**
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index eb5fa4158..c41b58d11 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -88,6 +88,10 @@ function hook_hook_info_alter(&$hooks) {
  *     uri elements of the entity, e.g. 'path' and 'options'. The actual entity
  *     uri can be constructed by passing these elements to url().
  *   - fieldable: Set to TRUE if you want your entity type to be fieldable.
+ *   - translation: An associative array of modules registered as field
+ *     translation handlers. Array keys are the module names, array values
+ *     can be any data structure the module uses to provide field translation.
+ *     Any empty value disallows the module to appear as a translation handler.
  *   - entity keys: An array describing how the Field API can extract the
  *     information it needs from the objects of the type. Elements:
  *     - id: The name of the property that contains the primary id of the
@@ -165,6 +169,9 @@ function hook_entity_info() {
       'revision table' => 'node_revision',
       'uri callback' => 'node_uri',
       'fieldable' => TRUE,
+      'translation' => array(
+        'locale' => TRUE,
+      ),
       'entity keys' => array(
         'id' => 'nid',
         'revision' => 'vid',