Issue #1326618 by Albert Volkman, ykhadilkar, oriol_e9g, daniel_j, xenophyle: API docs cleanup for locale module

core/modules/locale/locale-rtl.css

@@ -1,3 +1,8 @@
+/**
+ * @file
+ * CSS for the Locale module for right-to-left languages.
+ */
+
 #locale-translation-filter-form .form-item-language,
 #locale-translation-filter-form .form-item-translation,
 #locale-translation-filter-form .form-item-group {

core/modules/locale/locale.bulk.inc

@@ -12,7 +12,10 @@ use Drupal\Core\Language\Language;
 
 
 /**
- * User interface for the translation import screen.
+ * Form constructor for the translation import screen.
+ *
+ * @see locale_translate_import_form_submit()
+ * @ingroup forms
  */
 function locale_translate_import_form($form, &$form_state) {
   drupal_static_reset('language_list');
@@ -101,7 +104,7 @@ function locale_translate_import_form($form, &$form_state) {
 }
 
 /**
- * Processes the locale import form submission.
+ * Form submission handler for locale_translate_import_form().
  */
 function locale_translate_import_form_submit($form, &$form_state) {
   // Ensure we have the file uploaded.
@@ -135,7 +138,10 @@ function locale_translate_import_form_submit($form, &$form_state) {
 }
 
 /**
- * Builds form to export Gettext translation files.
+ * Form constructor for the Gettext translation files export form.
+ *
+ * @see locale_translate_export_form_submit()
+ * @ingroup forms
  */
 function locale_translate_export_form($form, &$form_state) {
   $languages = language_list();
@@ -207,7 +213,7 @@ function locale_translate_export_form($form, &$form_state) {
 }
 
 /**
- * Processes a translation (or template) export form submission.
+ * Form submission handler for locale_translate_export_form().
  */
 function locale_translate_export_form_submit($form, &$form_state) {
   // If template is required, language code is not given.
@@ -259,7 +265,7 @@ function locale_translate_export_form_submit($form, &$form_state) {
 }
 
 /**
- * Sets a batch for a newly added language.
+ * Sets a batch for a newly-added language.
  *
  * @param array $options
  *   An array with options that can have the following elements:

core/modules/locale/locale.datepicker.js

@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Datepicker JavaScript for the Locale module.
+ */
+
 (function ($) {
 
 "use strict";

core/modules/locale/locale.install

@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the locale module.
+ * Install, update, and uninstall functions for the Locale module.
  */
 
 /**
@@ -220,11 +220,11 @@ function locale_schema() {
  */
 
 /**
- * Drop textgroup support.
+ * Drops textgroup support.
  *
- * Update assumes i18n migrated this data before the update happened. Core
+ * Update assumes i18n migrated this data before the update happened. Core never
- * never used textgroups for anything, so it is not our job to find place
+ * used textgroups for anything, so it is not our job to find a place for the
- * for the data elsewhere.
+ * data elsewhere.
  */
 function locale_update_8000() {
   $subquery = db_select('locales_source', 'ls')

core/modules/locale/locale.module

@@ -2,13 +2,12 @@
 
 /**
  * @file
- *   Add language handling functionality and enables the translation of the
+ * Enables the translation of the user interface to languages other than English.
- *   user interface to languages other than English.
  *
- *   When enabled, multiple languages can be set up. The site interface
+ * When enabled, multiple languages can be set up. The site interface can be
- *   can be displayed in different languages, as well as nodes can have languages
+ * displayed in different languages, and nodes can have languages assigned. The
- *   assigned. The setup of languages and translations is completely web based.
+ * setup of languages and translations is completely web based. Gettext portable
- *   Gettext portable object files are supported.
+ * object files are supported.
  */
 
 use Drupal\locale\LocaleLookup;
@@ -66,9 +65,6 @@ const LOCALE_NOT_CUSTOMIZED = 0;
  */
 const LOCALE_CUSTOMIZED = 1;
 
-// ---------------------------------------------------------------------------------
-// Hook implementations
-
 /**
  * Implements hook_help().
  */
@@ -230,8 +226,6 @@ function locale_language_delete($language) {
   cache()->delete('locale:' . $language->langcode);
 }
 
-
-// ---------------------------------------------------------------------------------
 // Locale core functionality
 
 /**
@@ -570,7 +564,9 @@ function locale_form_language_admin_add_form_alter(&$form, &$form_state) {
 }
 
 /**
- * Set a batch for newly added language.
+ * Form submission handler for language_admin_add_form().
+ *
+ * Set a batch for a newly-added language.
  */
 function locale_form_language_admin_add_form_alter_submit($form, $form_state) {
   if (empty($form_state['values']['predefined_langcode']) || $form_state['values']['predefined_langcode'] == 'custom') {
@@ -599,14 +595,17 @@ function locale_form_language_admin_edit_form_alter(&$form, &$form_state) {
 }
 
 /**
- * Submission handler to record our custom setting.
+ * Form submission handler for language_admin_edit_form().
  */
 function locale_form_language_admin_edit_form_alter_submit($form, $form_state) {
   variable_set('locale_translate_english', $form_state['values']['locale_translate_english']);
 }
 
 /**
- * Utility function to tell if locale translates to English.
+ * Checks whether locale translates to English.
+ *
+ * @return bool
+ *   Returns TRUE if content should be translated to English, FALSE otherwise.
  */
 function locale_translate_english() {
   return variable_get('locale_translate_english', FALSE);

core/modules/locale/locale.pages.inc

@@ -8,7 +8,9 @@
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 
 /**
- * String search screen.
+ * Page callback: Shows the string search screen.
+ *
+ * @see locale_menu()
  */
 function locale_translate_page() {
   return array(
@@ -238,7 +240,11 @@ function locale_translate_filter_form_submit($form, &$form_state) {
 }
 
 /**
- * User interface for string editing as one table.
+ * Form constructor for the string editing form.
+ *
+ * @see locale_menu()
+ * @see locale_translate_edit_form_validate()
+ * @see locale_translate_edit_form_submit()
  *
  * @ingroup forms
  */
@@ -369,7 +375,9 @@ function locale_translate_edit_form($form, &$form_state) {
 }
 
 /**
- * Validate string editing form submissions.
+ * Form validation handler for locale_translate_edit_form().
+ *
+ * @see locale_translate_edit_form_submit()
  */
 function locale_translate_edit_form_validate($form, &$form_state) {
   $langcode = $form_state['values']['langcode'];
@@ -385,7 +393,9 @@ function locale_translate_edit_form_validate($form, &$form_state) {
 }
 
 /**
- * Process string editing form submissions.
+ * Form submission handler for locale_translate_edit_form().
+ *
+ * @see locale_translate_edit_form_validate()
  */
 function locale_translate_edit_form_submit($form, &$form_state) {
   $langcode = $form_state['values']['langcode'];

core/modules/locale/tests/locale_test.js

@@ -1,3 +1,7 @@
+/**
+ * @file
+ * JavaScript for locale_test.module.
+ */
 
 Drupal.t("Standard Call t");
 Drupal

core/modules/system/system.admin.inc

@@ -2835,7 +2835,9 @@ function system_add_date_formats_form_submit($form, &$form_state) {
 }
 
 /**
- * Display edit date format links for each language.
+ * Page callback: Displays edit date format links for each language.
+ *
+ * @see locale_menu()
  */
 function system_date_format_language_overview_page() {
   $header = array(
@@ -2856,7 +2858,14 @@ function system_date_format_language_overview_page() {
 }
 
 /**
- * Provide date localization configuration options to users.
+ * Form constructor for the date localization configuration form.
+ *
+ * @param $langcode
+ *   The code for the current language.
+ *
+ * @see locale_menu()
+ * @see system_date_format_localize_form_submit()
+ * @ingroup forms
  */
 function system_date_format_localize_form($form, &$form_state, $langcode) {
   // Display the current language name.
@@ -2915,7 +2924,7 @@ function system_date_format_localize_form($form, &$form_state, $langcode) {
 }
 
 /**
- * Submit handler for configuring localized date formats on the locale_date_format_form.
+ * Form submission handler for system_date_format_localize_form().
  */
 function system_date_format_localize_form_submit($form, &$form_state) {
   $langcode = $form_state['values']['langcode'];
@@ -2965,10 +2974,14 @@ function theme_system_date_format_localize_form($variables) {
 }
 
 /**
- * Reset locale specific date formats to the global defaults.
+ * Form constructor for the reset date format form.
  *
  * @param $langcode
  *   Language code, e.g. 'en'.
+ *
+ * @see locale_menu()
+ * @see system_date_format_localize_reset_form_submit()
+ * @ingroup forms
  */
 function system_date_format_localize_reset_form($form, &$form_state, $langcode) {
   $form['langcode'] = array('#type' => 'value', '#value' => $langcode);
@@ -2980,7 +2993,7 @@ function system_date_format_localize_reset_form($form, &$form_state, $langcode)
 }
 
 /**
- * Reset date formats for a specific language to global defaults.
+ * Form submission handler for locale_date_format_reset_form().
  */
 function system_date_format_localize_reset_form_submit($form, &$form_state) {
   db_delete('date_format_locale')