From 596d75a218b9bc6ee9a69b135951c6ac3c67ed71 Mon Sep 17 00:00:00 2001 From: Lars Toomre Date: Mon, 8 Oct 2012 21:30:54 -0400 Subject: [PATCH] Issue 1326618-39 by Lars Toomre: Clean up API docs for locale module. --- core/modules/locale/locale.admin.css | 5 ++ core/modules/locale/locale.admin.js | 5 ++ core/modules/locale/locale.api.php | 2 +- core/modules/locale/locale.bulk.inc | 66 ++++++++++++++++--------------- core/modules/locale/locale.bulk.js | 5 ++ core/modules/locale/locale.compare.inc | 50 ++++++++++++------------ core/modules/locale/locale.install | 4 +- core/modules/locale/locale.module | 53 +++++++++++++++---------- core/modules/locale/locale.pages.inc | 26 ++++++++++--- 9 files changed, 129 insertions(+), 87 deletions(-) diff --git a/core/modules/locale/locale.admin.css b/core/modules/locale/locale.admin.css index 4b252b6..d9d30c5 100644 --- a/core/modules/locale/locale.admin.css +++ b/core/modules/locale/locale.admin.css @@ -1,3 +1,8 @@ +/** + * @file + * Admin styling for the Locale module. + */ + #locale-translate-filter-form .form-item-langcode, #locale-translate-filter-form .form-item-translation, #locale-translate-filter-form .form-item-customized { diff --git a/core/modules/locale/locale.admin.js b/core/modules/locale/locale.admin.js index a9ded86..4a63b63 100644 --- a/core/modules/locale/locale.admin.js +++ b/core/modules/locale/locale.admin.js @@ -1,3 +1,8 @@ +/** + * @file + * Attaches behaviors for the administrative portion of Locale module. + */ + (function ($) { "use strict"; diff --git a/core/modules/locale/locale.api.php b/core/modules/locale/locale.api.php index b561ea0..5251de6 100644 --- a/core/modules/locale/locale.api.php +++ b/core/modules/locale/locale.api.php @@ -75,7 +75,7 @@ */ /** - * Alter the list of projects to be updated by locale's interface translation. + * Alters the list of projects to be updated by locale's interface translation. * * Locale module attempts to update the translation of those modules returned * by update_get_projects(). Using this hook, the data returned by diff --git a/core/modules/locale/locale.bulk.inc b/core/modules/locale/locale.bulk.inc index b7850db..e139fad 100644 --- a/core/modules/locale/locale.bulk.inc +++ b/core/modules/locale/locale.bulk.inc @@ -10,7 +10,6 @@ use Drupal\locale\PoDatabaseReader; use Drupal\Core\Language\Language; - /** * Form constructor for the translation import screen. * @@ -269,14 +268,14 @@ function locale_translate_export_form_submit($form, &$form_state) { * * @param array $options * An array with options that can have the following elements: - * - 'langcode': The language code, required. - * - 'overwrite_options': Overwrite options array as defined in + * - langcode: The language code, required. + * - overwrite_options: Overwrite options array as defined in * Drupal\locale\PoDatabaseWriter. Optional, defaults to an empty array. - * - 'customized': Flag indicating whether the strings imported from $file - * are customized translations or come from a community source. Use + * - customized: Flag indicating whether the strings imported from $file are + * customized translations or come from a community source. Use * LOCALE_CUSTOMIZED or LOCALE_NOT_CUSTOMIZED. Optional, defaults to * LOCALE_NOT_CUSTOMIZED. - * - 'finish_feedback': Whether or not to give feedback to the user when the + * - finish_feedback: Whether or not to give feedback to the user when the * batch is finished. Optional, defaults to TRUE. */ function locale_translate_add_language_set_batch($options) { @@ -293,21 +292,20 @@ function locale_translate_add_language_set_batch($options) { } /** - * Prepare a batch to import all translations. + * Prepares a batch to import all translations. * * @param array $options * An array with options that can have the following elements: - * - 'langcode': The language code. Optional, defaults to NULL, which means - * that the language will be detected from the name of the files. - * - 'overwrite_options': Overwrite options array as defined in + * - langcode: The language code. Optional, defaults to NULL, which means that + * the language will be detected from the name of the files. + * - overwrite_options: Overwrite options array as defined in * Drupal\locale\PoDatabaseWriter. Optional, defaults to an empty array. - * - 'customized': Flag indicating whether the strings imported from $file - * are customized translations or come from a community source. Use + * - customized: Flag indicating whether the strings imported from $file are + * customized translations or come from a community source. Use * LOCALE_CUSTOMIZED or LOCALE_NOT_CUSTOMIZED. Optional, defaults to * LOCALE_NOT_CUSTOMIZED. - * - 'finish_feedback': Whether or not to give feedback to the user when the + * - finish_feedback: Whether or not to give feedback to the user when the * batch is finished. Optional, defaults to TRUE. - * * @param $force * (optional) Import all available files, even if they were imported before. * @@ -352,11 +350,11 @@ function locale_translate_batch_import_files($options, $force = FALSE) { } /** - * Get an array of available interface translation file. + * Gets an array of available interface translation file. * * @param $langcode - * The langcode for the interface translation files. Pass NULL to get all - * available interface translation files. + * (optional) The langcode for the interface translation files. Pass NULL to + * get all available interface translation files. Defaults to NULL. * * @return array * An array of interface translation files. @@ -378,18 +376,17 @@ function locale_translate_get_interface_translation_files($langcode = NULL) { * * @param $files * Array of file objects to import. - * * @param array $options * An array with options that can have the following elements: - * - 'langcode': The language code. Optional, defaults to NULL, which means - * that the language will be detected from the name of the files. - * - 'overwrite_options': Overwrite options array as defined in + * - langcode: The language code. Optional, defaults to NULL, which means that + * the language will be detected from the name of the files. + * - overwrite_options: Overwrite options array as defined in * Drupal\locale\PoDatabaseWriter. Optional, defaults to an empty array. - * - 'customized': Flag indicating whether the strings imported from $file - * are customized translations or come from a community source. Use + * - customized: Flag indicating whether the strings imported from $file are + * customized translations or come from a community source. Use * LOCALE_CUSTOMIZED or LOCALE_NOT_CUSTOMIZED. Optional, defaults to * LOCALE_NOT_CUSTOMIZED. - * - 'finish_feedback': Whether or not to give feedback to the user when the + * - finish_feedback: Whether or not to give feedback to the user when the * batch is finished. Optional, defaults to TRUE. * * @return @@ -424,24 +421,22 @@ function locale_translate_batch_build($files, $options) { } /** - * Perform interface translation import as a batch step. + * Performs interface translation import as a batch step. * * The given filepath is matched against ending with '{langcode}.po'. When * matched the filepath is added to batch context. * * @param $filepath * Path to a file to import. - * * @param array $options * An array with options that can have the following elements: - * - 'langcode': The language code, required. - * - 'overwrite_options': Overwrite options array as defined in + * - langcode: The language code, required. + * - overwrite_options: Overwrite options array as defined in * Drupal\locale\PoDatabaseWriter. Optional, defaults to an empty array. - * - 'customized': Flag indicating whether the strings imported from $file - * are customized translations or come from a community source. Use + * - customized: Flag indicating whether the strings imported from $file are + * customized translations or come from a community source. Use * LOCALE_CUSTOMIZED or LOCALE_NOT_CUSTOMIZED. Optional, defaults to * LOCALE_NOT_CUSTOMIZED. - * * @param $context * Contains a list of files imported. */ @@ -515,6 +510,13 @@ function locale_translate_batch_import($filepath, $options, &$context) { /** * Finished callback of system page locale import batch. + * + * @param bool $success + * A Boolean indicating the success status of the batch operation. + * @param array $results + * An array with an arbitrary number of batch step results. + * + * @see locale_translate_batch_import() */ function locale_translate_batch_finished($success, $results) { if ($success) { @@ -571,7 +573,7 @@ function locale_translate_file_create($filepath) { } /** - * Update the {locale_file} table. + * Updates the {locale_file} table. * * @param $file * Object representing the file just imported. diff --git a/core/modules/locale/locale.bulk.js b/core/modules/locale/locale.bulk.js index 02cee5e..3fe6ed6 100644 --- a/core/modules/locale/locale.bulk.js +++ b/core/modules/locale/locale.bulk.js @@ -1,3 +1,8 @@ +/** + * @file + * Attaches behaviors for bulk operations portion of Locale module. + */ + (function ($) { "use strict"; diff --git a/core/modules/locale/locale.compare.inc b/core/modules/locale/locale.compare.inc index 039eba3..c1cd7c2 100644 --- a/core/modules/locale/locale.compare.inc +++ b/core/modules/locale/locale.compare.inc @@ -15,22 +15,22 @@ use Drupal\Core\Cache; /** - * Get array of projects which are available for interface translation. + * Gets array of projects which are available for interface translation. * * This project data contains all projects which will be checked for available * interface translations. * - * For full functionality this function depends on Update module. - * When Update module is enabled the project data will contain the most recent - * module status; both in enabled status as in version. When Update module is - * disabled this function will return the last known module state. The status - * will only be updated once Update module is enabled. - * - * @see locale_translation_build_projects(). + * For full functionality, this function depends on the Update module. When + * Update module is enabled the project data will contain the most recent module + * status; both in enabled status as in version. When Update module is disabled + * this function will return the last known module state. The status will only + * be updated once Update module is enabled. * * @return array * Array of project data for translation update. See * locale_translation_build_projects() for details. + * + * @see locale_translation_build_projects(). */ function locale_translation_get_projects() { $projects = &drupal_static(__FUNCTION__, array()); @@ -56,7 +56,7 @@ function locale_translation_get_projects() { } /** - * Clear the project data table. + * Clears the project data table. */ function locale_translation_flush_projects() { db_truncate('locale_project')->execute(); @@ -74,14 +74,14 @@ function locale_translation_flush_projects() { * * @return array * Array of project data: - * - "name": Project system name. - * - "project_type": Project type, e.g. 'module', 'theme'. - * - "core": Core release version, e.g. 8.x - * - "version": Project release version, e.g. 8.x-1.0 + * - name: Project system name. + * - project_type: Project type, e.g. 'module', 'theme'. + * - core: Core release version, e.g. 8.x. + * - version: Project release version, e.g. 8.x-1.0. * See http://drupalcode.org/project/drupalorg.git/blob/refs/heads/7.x-3.x:/drupalorg_project/plugins/release_packager/DrupalorgProjectPackageRelease.class.php#l219 * for how the version strings are created. - * - "server_pattern": Translation server po file pattern. - * - "status": Project status, 1 = enabled. + * - server_pattern: Translation server po file pattern. + * - status: Project status, 1 = enabled. */ function locale_translation_build_projects() { // This function depends on Update module. We degrade gracefully. @@ -161,7 +161,7 @@ function locale_translation_build_projects() { } /** - * Fetch an array of projects for translation update. + * Fetches an array of projects for translation update. * * @return array * Array of project data including .info file data. @@ -198,7 +198,7 @@ function locale_translation_project_list() { } /** - * Prepare module and theme data. + * Prepares module and theme data. * * Modify .info file data before it is processed by update_process_info_list(). * In order for update_process_info_list() to recognize a project, it requires @@ -230,11 +230,11 @@ function _locale_translation_prepare_project_list($data, $type) { } /** - * Retrieve data for default server. + * Retrieves data for default server. * * @return array * Array of server parameters: - * - "server_pattern": URL containing po file pattern. + * - server_pattern: URL containing po file pattern. */ function locale_translation_default_translation_server() { $config = config('locale.settings'); @@ -244,17 +244,17 @@ function locale_translation_default_translation_server() { } /** - * Build path to translation source, out of a server path replacement pattern. + * Builds path to translation source, out of a server path replacement pattern. * * @param stdClass $project * Project object containing data to be inserted in the template. * @param string $template * String containing placeholders. Available placeholders: - * - "%project": Project name. - * - "%version": Project version. - * - "%core": Project core version. - * - "%language": Language code. - * - "%filename": Project file name. + * - %project: Project name. + * - %version: Project version. + * - %core: Project core version. + * - %language: Language code. + * - %filename: Project file name. * * @return string * String with replaced placeholders. diff --git a/core/modules/locale/locale.install b/core/modules/locale/locale.install index 1453456..50c2df8 100644 --- a/core/modules/locale/locale.install +++ b/core/modules/locale/locale.install @@ -297,7 +297,7 @@ function locale_update_8001() { } /** - * Removes duplicates in {locales_source}. + * Remove duplicates in {locales_source}. * * Aggressively removes duplicates that has not already been removed by * locale_update_7004() in Drupal 7.x. @@ -327,7 +327,7 @@ function locale_update_8002() { } /** - * Converts language domains to new format. + * Convert language domains to new format. * * @ingroup config_upgrade */ diff --git a/core/modules/locale/locale.module b/core/modules/locale/locale.module index b2bfa95..81e0b76 100644 --- a/core/modules/locale/locale.module +++ b/core/modules/locale/locale.module @@ -2,7 +2,7 @@ /** * @file - * Enables the translation of the user interface to languages other than English. + * Enables translation of the user interface to languages other than English. * * When enabled, multiple languages can be set up. The site interface can be * displayed in different languages, and nodes can have languages assigned. The @@ -227,21 +227,22 @@ function locale_language_delete($language) { cache()->delete('locale:' . $language->langcode); } -// Locale core functionality - /** * Provides interface translation services. * * This function is called from t() to translate a string if needed. * - * @param $string - * A string to look up translation for. If omitted, all the - * cached strings will be returned in all languages already - * used on the page. - * @param $context - * The context of this string. - * @param $langcode - * Language code to use for the lookup. + * @param string $string + * (optional) A string to look up translation for. If omitted, all the cached + * strings will be returned in all languages already used on the page. + * Defaults to NULL. + * @param string $context + * (optional) The context of this string. Defaults to NULL. + * @param string $langcode + * (optional) Language code to use for the lookup. Defaults to NULL. + * + * @return string + * Either the translated string or the original string */ function locale($string = NULL, $context = NULL, $langcode = NULL) { $language_interface = language(LANGUAGE_TYPE_INTERFACE); @@ -282,7 +283,7 @@ function locale($string = NULL, $context = NULL, $langcode = NULL) { } /** - * Reset static variables used by locale(). + * Resets static variables used by locale(). */ function locale_reset() { drupal_static_reset('locale'); @@ -310,8 +311,9 @@ function locale_storage() { * @param $count * Number to return plural for. * @param $langcode - * Optional language code to translate to a language other than - * what is used to display the page. + * (optional) The language code to translate to a language other than what is + * used to display the page. Defaults to NULL. + * * @return * The numeric index of the plural variant to use for this $langcode and * $count combination or -1 if the language was not found or does not have a @@ -354,7 +356,6 @@ function locale_get_plural($count, $langcode = NULL) { return $plural_indexes[$langcode][$count]; } - /** * Implements hook_modules_installed(). */ @@ -670,7 +671,7 @@ function locale_preprocess_node(&$variables) { } /** - * Check that a string is safe to be added or imported as a translation. + * Checks that a string is safe to be added or imported as a translation. * * This test can be used to detect possibly bad translation strings. It should * not have any false positives. But it is only a test, not a transformation, @@ -688,8 +689,13 @@ function locale_string_is_safe($string) { } /** - * Parses a JavaScript file, extracts strings wrapped in Drupal.t() and - * Drupal.formatPlural() and inserts them into the database. + * Parses a Javascript file and adds extracted string to database. + * + * This function parses a JavaScript file, extracts strings wrapped in + * Drupal.t() and Drupal.formatPlural() and inserts them into the database. + * + * @param string $filepath + * A file path that may contain a query string. */ function _locale_parse_js_file($filepath) { // The file path might contain a query string, so make sure we only use the @@ -801,7 +807,7 @@ function _locale_parse_js_file($filepath) { } /** - * Force the JavaScript translation file(s) to be refreshed. + * Forces the JavaScript translation file(s) to be refreshed. * * This function sets a refresh flag for a specified language, or all * languages except English, if none specified. JavaScript translation @@ -809,7 +815,8 @@ function _locale_parse_js_file($filepath) { * request is served in that language. * * @param $langcode - * The language code for which the file needs to be refreshed. + * (optional) The language code for which the file needs to be refreshed. + * Defaults to NULL. * * @return * New content of the 'javascript_parsed' variable. @@ -840,7 +847,11 @@ function _locale_invalidate_js($langcode = NULL) { * (Re-)Creates the JavaScript translation file for a language. * * @param $langcode - * The language, the translation file should be (re)created for. + * (optional) The language, the translation file should be (re)created for. + * Defaults to NULL. + * + * @return bool + * TRUE indicates the desired operation was successful; othrewise, FALSE. */ function _locale_rebuild_js($langcode = NULL) { if (!isset($langcode)) { diff --git a/core/modules/locale/locale.pages.inc b/core/modules/locale/locale.pages.inc index a6fb751..e73fa3e 100644 --- a/core/modules/locale/locale.pages.inc +++ b/core/modules/locale/locale.pages.inc @@ -61,7 +61,10 @@ function locale_translate_filter_load_strings() { } /** - * Build array out of search criteria specified in request variables. + * Builds array out of search criteria specified in request variables. + * + * @return array + * A filtered list of translation values. */ function locale_translate_filter_values() { $filter_values = &drupal_static(__FUNCTION__); @@ -91,7 +94,10 @@ function locale_translate_filter_values() { } /** - * List locale translation filters that can be applied. + * Lists locale translation filters that can be applied. + * + * @return array + * An array of translation filters thta are avilable. */ function locale_translate_filters() { $filters = array(); @@ -154,7 +160,9 @@ function locale_translate_filters() { } /** - * Return form for locale translation filters. + * Form constructor for locale translation filters form. + * + * @see locale_translate_filter_form_submit() * * @ingroup forms */ @@ -218,7 +226,7 @@ function locale_translate_filter_form($form, &$form_state) { } /** - * Process result from locale translation filter form. + * Form submissiion handler for locale_translate_filter_form(). */ function locale_translate_filter_form_submit($form, &$form_state) { $op = $form_state['values']['op']; @@ -245,8 +253,8 @@ function locale_translate_filter_form_submit($form, &$form_state) { * Form constructor for the string editing form. * * @see locale_menu() - * @see locale_translate_edit_form_validate() * @see locale_translate_edit_form_submit() + * @see locale_translate_edit_form_validate() * * @ingroup forms */ @@ -441,7 +449,13 @@ function locale_translate_edit_form_submit($form, &$form_state) { } /** - * Default theme function for translatione edit form. + * Returns HTML for translation edit form. + * + * @param $variables + * An associative array containing: + * - form: The form definition array. + * + * @ingroup themeable */ function theme_locale_translate_edit_form_strings($variables) { $output = ''; -- 1.7.6.msysgit.0