diff --git a/core/includes/language.inc b/core/includes/language.inc
index 2c46c76..4b19e26 100644
--- a/core/includes/language.inc
+++ b/core/includes/language.inc
@@ -2,7 +2,9 @@
 
 /**
  * @file
- * Multiple language handling functionality.
+ * Language Negotiation API.
+ *
+ * @see http://drupal.org/node/1497272
  */
 
 /**
@@ -11,6 +13,123 @@
 const LANGUAGE_NEGOTIATION_DEFAULT = 'language-default';
 
 /**
+ * @defgroup language_negotiation Language Negotiation API functionality
+ * @{
+ * Functions to customize the language types and the negotiation process.
+ *
+ * It is possible to customize the language negotiation process both for how we
+ * detect the user's language and also for what type of data they are
+ * requesting.
+ *
+ * The language negotiation API is based on two major concepts:
+ * - Language types, which describe the possible types of translatable content.
+ * - Language methods, which allow Drupal to detect which language it should
+ *   serve to the user.
+ *
+ * Drupal core defines three built-in language types:
+ * - Interface language: This 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 with 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.
+ *
+ * Core includes the following methods:
+ * - 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.
+ *
+ * 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
+ * can be adjusted in the user interface where the language methods 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
+ * // Implements hook_language_types_info_alter().
+ * function language_negotiation_language_types_info_alter(&$language_types) {
+ *   unset($language_types[LANGUAGE_TYPE_CONTENT]['fixed']);
+ * }
+ * ?>
+ * @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.
+ *
+ * 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 provider 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
+ * // Implements hook_language_negotiation_info_alter().
+ * function mymodule_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 +550,7 @@ function language_fallback_get_candidates($type = LANGUAGE_TYPE_CONTENT) {
 
   return $fallback_candidates;
 }
+
+/**
+ * @} End of "language_negotiation"
+ */