diff --git a/core/includes/language.inc b/core/includes/language.inc
index 76c4318..dbe465d 100644
--- a/core/includes/language.inc
+++ b/core/includes/language.inc
@@ -2,7 +2,13 @@
 
 /**
  * @file
- * Multiple language handling functionality.
+ * Language Negotiation API
+ *
+ * This file manages the negotiation of languages for users visiting your Drupal
+ * site.  The API is used by the locale module as the primary core
+ * implementation as well as any contrib modules.
+ *
+ * @see http://drupal.org/node/1497272
  */
 
 /**
@@ -11,6 +17,19 @@
 const LANGUAGE_NEGOTIATION_DEFAULT = 'language-default';
 
 /**
+ * @defgroup languages-negotiation Language Negotiation API
+ * functionality
+ * @{
+ * Functions for language negotiation.
+ *
+ * These functions manage the negotiation of languages for users visiting your
+ * Drupal site.  The API is used by the locale module as the primary core
+ * implementation as well as any contrib modules.
+ *
+ * @see http://drupal.org/node/1497272
+ */
+
+/**
  * Chooses a language for the given type based on language negotiation settings.
  *
  * @param $type
@@ -431,3 +450,7 @@ function language_fallback_get_candidates($type = LANGUAGE_TYPE_CONTENT) {
 
   return $fallback_candidates;
 }
+
+/**
+ * @} End of "languages-negotiation"
+ */
diff --git a/core/modules/field/field.multilingual.inc b/core/modules/field/field.multilingual.inc
index a4f5f8f..532c917 100644
--- a/core/modules/field/field.multilingual.inc
+++ b/core/modules/field/field.multilingual.inc
@@ -10,20 +10,59 @@
  * @{
  * Handling of multilingual fields.
  *
- * Fields natively implement multilingual support, and all fields use the
- * following structure:
+ * Fields natively implement multilingual support by holding multiple values 
+ * of the field array. 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_NOT_SPECIFIED.
- * - For translatable fields this set can contain any language code. By default
- *   it is the list returned by field_content_languages(), which contains all
- *   installed languages with the addition of LANGUAGE_NOT_SPECIFIED. This
- *   default can be altered by modules implementing
- *   hook_field_available_languages_alter().
  *
+ * By default a single-language site in English without the locale module 
+ * enabled uses LANGUAGE_NONE as the $langcode, and there is always only
+ * one language variant for each field.
+ * @code
+ * $entity->body[und][0][value];
+ * $entity->langcode = 'und';
+ * @endcode
+ *
+ * With Locale module enabled (as well as with Content Translation), fields
+ * will not have their own language information, but LANGUAGE_NONE is used
+ * to signify that we don't have that specified. The whole entity with all 
+ * its properties and fields is assumed to have the entity language code 
+ * assigned (conceptually).
+ * @code
+ * $entity->body[und][0][value];
+ * $entity->langcode = 'en';
+ * @endcode
+ *
+ * Field translation is pluggable, but the only known implementation
+ * is the contributed Entity translation module that provides a user
+ * interface to field-translation enable entities and change the
+ * translatability on fields. 
+ *
+ * When we enable field translation, a field that does not have translation 
+ * enabled will always be LANGUAGE_NONE, and no other language values will be
+ * present. The meaning of this is different from the above. It means that the
+ * field will have the same value across all translations. This is also called
+ * a shared field.  The $entity->langcode value will persist to represent the
+ * language of the properties of the entity, such as the title, author as well 
+ * as signify the original language that the entity was saved with. That 
+ * information can be useful for permission and workflow purposes.
+ * @code
+ * $entity->body[und][0][value]; // not translatable (shared)
+ * $entity->langcode = 'en'; // applies to properties of the entity
+ * @endcode
+ *
+ * For a field with translation enabled in field settings, multiple variants
+ * of the value may be available in any of the enabled languages.
+ * Data that was created prior to enabling the translation will remain, however, it will be ignored
+ * by Drupal. The LANGUAGE_NONE version of the field in this case serves only to preserve the 
+ * historic configuration and can be safely deleted when it is no longer used.
+ * @code
+ * $entity->body[en][0][value]; // translatble
+ * $entity->body[und][0][value]; // ignored by Drupal
+ * $entity->langcode = 'en'; // applies to properties of the entity
+ * @endcode
+ * 
  * 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']
@@ -32,6 +71,8 @@
  * module registering itself via hook_entity_info() to handle field
  * translations.
  *
+ * Multilingual Field API
+ *
  * 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
@@ -59,6 +100,10 @@
  *   it possible to choose the first approach. The display language for each
  *   field is returned by field_language().
  *
+ * Accessing Multilingual Fields
+ *
+ * @see field_get_items() 
+ *
  * See @link field Field API @endlink for information about the other parts of
  * the Field API.
  */