diff --git a/core/includes/language.inc b/core/includes/language.inc
index 76c4318..95fda92 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,153 @@
 const LANGUAGE_NEGOTIATION_DEFAULT = 'language-default';
 
 /**
+ * @defgroup languages-negotiation Language Negotiation API
+ * functionality
+ * @{
+ * Language Negotiation API
+ *
+ * It is possible to customize the language negotiation process both for how we
+ * detect the user's language and also on what type of data they are requesting.
+ *
+ * The language negotiation API is based on two major concepts:
+ *
+ * - Language types, which describes the possible types of translatable content
+ * - Language providers, which allows Drupal to detect which language it should
+ *   serve to the user (note that language providers are called language methods
+ *   in Drupal 8)
+ *
+ * Defaults provided by Drupal
+ *
+ * Language Types
+ *
+ * Drupal core defines three built-in language types:
+ *
+ * Interface language
+ *     It is the page's main language. It is used to present translated user
+ *     interface elements such as titles, labels, help text, and messages.
+ * Content language
+ *     This is used to choose in which language to display content that is
+ *     available in more than one language (see the multilingual capabilities of
+ *     the new Field API for details).
+ * URL language
+ *     This is the language associated to URLs. When generating a URL, this
+ *     value will be used by url() as a default if no explicit preference is
+ *     provided.
+ *
+ * Different language types often share the same values, but the they can have
+ * independent values if needed.
+ *
+ * Language Providers
+ *
+ * Core includes the following providers:
+ *
+ * - URL: Determine the language from the URL (path prefix or domain).
+ * - Session: Determine the language from a request/session parameter.
+ * - User: Follow the user's language preference.
+ * - Browser: Determine the language from the browser's language settings.
+ * - Default language: Use the default site language.
+ *
+ * Here is an image which shows the relationship between types and providers:
+ *
+ * Drupal language negotiation - possible tracks
+ *
+ * Defining language types
+ *
+ * Starting in Drupal 7, the language API allows contributed modules to define
+ * additional language types through hook_language_types_info() and alter
+ * existing language type definitions through hook_language_types_info_alter().
+ *
+ * A language type may be configurable or fixed. A configurable language type
+ * appears in the Configuration > Regional and language > Languages > Detection
+ * and selection page, where the language providers for that language type can
+ * be configured. There are also fixed language types that have predetermined
+ * (module-defined) negotiation settings and, thus, do not appear in the
+ * configuration page. Here is a code snippet that makes the content language
+ * (which by default inherits the interface language's values) configurable:
+ *
+ * @code
+ * <?php
+ * // Implements hook_language_types_info_alter().
+ * function language_negotiation_language_types_info_alter(&$language_types) {
+ *   $language_types[LANGUAGE_TYPE_CONTENT] = array(
+ *     'name' => t('Content'),
+ *     'description' => t('If a piece of content is available in multiple
+ * languages, the one matching the <em>content</em> language will be used.'),
+ *   );
+ * }
+ * ?>
+ * @endcode
+ *
+ * Every configurable language type will have its own (independent) language
+ * switcher block. Obviously, if two language types are configured the same way,
+ * their language switcher blocks will be functionally identical and will act on
+ * both language types.
+ *
+ * In Drupal 6.x, there is only one language type, named just language. During
+ * language initialization the selected language negotiation settings are used
+ * to determine its value. In Drupal 7.x, the same process happens for each
+ * defined language type, see drupal_language_initialize() for details.
+ *
+ * Defining custom language providers
+ *
+ * Every language type can have different language negotiation settings, i.e.
+ * every language type can have a different set of language detection methods,
+ * or providers, assigned to it.
+ *
+ * Language providers are simple callback functions that implement a particular
+ * logic to return a language code. For instance, the URL language provider
+ * searches for a valid path prefix or domain name in the current request URL.
+ * If a language provider does not return a valid language code, the next
+ * provider associated to the language type (based on provider weight) is
+ * invoked. This way the concept of fallback is generalized and untied from the
+ * fixed path prefix > user preference > browser settings > default language
+ * scheme used in Drupal 6.x.
+ *
+ * Also language providers are module-definable through
+ * hook_language_negotiation_info() and language providers definitions can be
+ * altered through hook_language_negotiation_info_alter(). Here is an example
+ * snippet that lets path prefixes be ignored for administrative paths:
+ *
+ * @code
+ * <?php
+ * // Implements hook_language_negotiation_info_alter().
+ * function language_negotiation_language_negotiation_info_alter(&$providers) {
+ *   $providers[LOCALE_LANGUAGE_NEGOTIATION_URL]['callbacks']['language']
+ * = 'language_negotiation_from_url';
+ *   $providers[LOCALE_LANGUAGE_NEGOTIATION_URL]['file'] =
+ * drupal_get_path('module', 'language_negotiation') .
+ * '/language_negotiation.module';
+ * }
+ *
+ * // Identify language via URL prefix or domain excluding administrative paths.
+ * function language_negotiation_from_url($languages) {
+ *   // Use the core URL language provider to get a valid language code.
+ *   require DRUPAL_ROOT . '/includes/locale.inc';
+ *   $langcode = locale_language_from_url($languages);
+ *
+ *   // If we have an administrative path just return the default language.
+ *   if (isset($_GET['q']) && strtok($_GET['q'], '/') == 'admin') {
+ *     return language_default()->language;
+ *   }
+ *
+ *   return $langcode;
+ * }
+ * ?>
+ * @endcode
+ *
+ * Language provider definitions may include two more callbacks besides the
+ * language provider itself:
+ *
+ * - If the language provider can take advantage of a language switcher block,
+ *   the switcher callback will allow it to return the language switch links
+ *   that suit its logic, see locale_language_switcher_url() for an example.
+ * - If the language provider needs to rewrite URLs, it can specify an
+ *   url_rewrite callback which will provide the rewriting logic.
+ *
+ * @see http://drupal.org/node/1497272
+ */
+
+/**
  * Chooses a language for the given type based on language negotiation settings.
  *
  * @param $type
@@ -431,3 +584,7 @@ function language_fallback_get_candidates($type = LANGUAGE_TYPE_CONTENT) {
 
   return $fallback_candidates;
 }
+
+/**
+ * @} End of "languages-negotiation"
+ */