diff --git a/core/modules/locale/locale.api.php b/core/modules/locale/locale.api.php
index e1ad3a1..e073630 100644
--- a/core/modules/locale/locale.api.php
+++ b/core/modules/locale/locale.api.php
@@ -1,25 +1,46 @@
 <?php
 
 /**
+ * @file
+ * Hooks provided by the Locale module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
  * Alter the list of projects to be updated by locale's interface translation.
  *
- * @todo more description.
+ * Locale module attempts to update the translation of those modules returned
+ * by update_get_projects(). Using this hook this data can be altered or
+ * extended.
+ *
+ * Custom modules can be added using this hook to let Locale module import
+ * the translations. This can be used a part of a translation staging solution.
+ *
+ * Modules or distributions that use a dedicated translation server should use
+ * this hook to specify the translation sever parameters. These parameters are:
+ * - "interface translation server": server name for the user interface.
+ * - "interface translation server url": URL of the xml file containing
+ *   tranlation server parameters.
+ * - "interface translation server pattern": URL of the .po translation files
+ *   used to download the files from. The URL contains tokens which will be
+ *   replaced by appropriate values.
+ * The following tokens are available for the server pattern:
+ * - "%core": Core version. Value example: "8.x".
+ * - "%project": Project name. Value examples: "drupal", "media_gallery".
+ * - "%release": Project version release. Value examples: "8.1", "8.x-1.0".
+ * - "%language": Language code. Value examples: "fr", "pt-pt".
  *
- * @param $projects
- *   Array of project data.
+ * @param array $projects
+ *   Project data as returned by update_get_projects().
  *
  * @see locale_project_list().
  */
 function hook_locale_translation_projects_alter(&$projects) {
-  // The $projects array contains the project data returned by
-  // update_get_projects(). A number of the array elements are described in
-  // the documentation of hook_update_projects_alter().
-
-  // In the .info file of a project a localization server can be specified.
-  // Using this hook the localization server specification can be altered or
-  // added. The 'interface translation server pattern' element is optional but
-  // can be specified to override the translation download path specified in the
-  // 10n_server.xml file.
+  // Use of a custom translation sever.
   $projects['existing_example_project'] = array(
     'info' => array(
       'interface translation server' => 'example.com',
@@ -32,20 +53,77 @@ function hook_locale_translation_projects_alter(&$projects) {
 /**
  * Allows to define or alter project definitions for interface translation.
  *
+ * Modules hosted on drupal.org, a project definition is automatically added to
+ * the .info file. Only modules with this project defintion are discovered by
+ * the update module and use it to check for new releases. Locale module uses
+ * the same data to build a list of module to check for new tranlations.
+ * Therefore modules not hosted at drupal.org, such as custom modules, custom
+ * themes, features and distributions, need a way to identify themselves to
+ * the Locale module if they have translations that require to be updated.
+ *
+ * Custom module which contain new strings should provide po file(s) containing
+ * source strings and string translations in gettext format. The translation
+ * file can be located both local and remote. The following defintion is
+ * required by the Locale module to recognize and import the translations.
+ * Example:
+ * @code
+ * // Po file located in local file system.
+ * $projects['example_module'] = array(
+ *   'type' => 'module',
+ *   'info' => array(
+ *     'project' => 'example_module',
+ *     'interface translation server pattern' => 'sites/example.com/modules/custom/example_module/%project-%version.%language.po',
+ *   ),
+ * );
+ *
+ * // Po file located at a remote translation server.
+ * $projects['example_module'] = array(
+ *   'type' => 'module',
+ *   'info' => array(
+ *     'project' => 'example_module',
+ *     'interface translation server' => 'example.com',
+ *     'interface translation server url' => 'http://example.com/files/translations/l10n_server.xml',
+ *     'interface translation server pattern' => 'http://example.com/files/translations/%core/%project/%project-%version.%language.po',
+ *   ),
+ * );
+ * @endcode
+ *
+ * Multiple custom modules sharing the same po file should have matching
+ * definitions. Such as modules and sub-modules or multiple modules in the same
+ * project/code tree. Both "project", "version" and "interface translation
+ * server" definitions should match.
+ * @code
+ * $projects['other_example_module'] = array(
+ *   'type' => 'module',
+ *   'info' => array(
+ *     'project' => 'example_module',
+ *     'version' => '1.1',
+ *     'interface translation server pattern' => 'sites/example.com/modules/custom/example_module/%project-%version.%language.po',
+ *   ),
+ * );
+ * @endcode
+ *
+ * The following parameters are available:
+ * - "project": project or module name of the module. Required.
+ * - "interface translation server": server name for the user interface.
+ * - "interface translation server url": URL of the xml file containing
+ *   tranlation server parameters.
+ * - "interface translation server pattern": URL of the .po translation files
+ *   used to download the files from. The URL contains tokens which will be
+ *   replaced by appropriate values.
+ * The following tokens are available for the server pattern:
+ * - "%core": Core version. Value example: "8.x".
+ * - "%project": Project name. Value examples: "drupal", "media_gallery".
+ * - "%release": Project version release. Value examples: "8.1", "8.x-1.0".
+ * - "%language": Language code. Value examples: "fr", "pt-pt".
+ *
  * Themes can implement this hook too in their template.php file.
  *
  * @return
  *   Array of project defintions.
  */
 function hook_locale_translation_additional_project_info() {
-  // If your custom module contains new strings the Locale interface translation
-  // can be configured to recognize and import the translations.
-  // The tanslations can be located in the local file system or remotely in a
-  // translation server (similar to localize.drupal.org).
-  // Required: type. "project" is required if the "example_project" is a custom
-  // module and not a contributed module.
-
-  // Po file located at a remote translation server.
+  // Custom module with translation on a remote translation server.
   $projects['example_module'] = array(
     'type' => 'module',
     'info' => array(
@@ -56,34 +134,8 @@ function hook_locale_translation_additional_project_info() {
     ),
   );
 
-  // Po file located in local file system.
-  $projects['example_module'] = array(
-    'type' => 'module',
-    'info' => array(
-      'project' => 'example_module',
-      'interface translation server pattern' => 'sites/example.com/modules/custom/example_module/%project-%version.%language.po',
-    ),
-  );
-
-  // When multiple custom modules share the same po file, their project
-  // definitions should match. Both "project", "version" and "interface
-  // translation server" definitions are used as part of the po file format and
-  // should match.
-  // In this example the above example module and the other_example_module share
-  // the same po file. "project", "version" and "interface translation server
-  // pattern" are overridden to match the above po file name as provided by the
-  // example_module.
-  $projects['other_example_module'] = array(
-    'type' => 'module',
-    'info' => array(
-      'project' => 'example_module',
-      'version' => '1.1',
-      'interface translation server pattern' => 'sites/example.com/modules/custom/example_module/%project-%version.%language.po',
-    ),
-  );
-
-  // Themes can implement this hook too.
-  $projects['zen'] = array(
+  // Custom theme with translation on a remote translation server.
+  $projects['example_theme'] = array(
     'type' => 'theme',
     'info' => array(
       'interface translation server' => 'example.com',
@@ -95,10 +147,6 @@ function hook_locale_translation_additional_project_info() {
   return $projects;
 }
 
-// @todo Remove this list.
-// Whish list
-// ==========
-// Let the translation server provide the name and pattern details, instead
-//   of defining it in the .info file or in code.
-//   Will this work if an installation profile or a custom module provides
-//   it's own info hook and needs to download translations from a remote server?
+/**
+ * @} End of "addtogroup hooks".
+ */