diff --git a/core/modules/translation/translation.module b/core/modules/translation/translation.module index ccd13c5..7012829 100644 --- a/core/modules/translation/translation.module +++ b/core/modules/translation/translation.module @@ -2,21 +2,21 @@ /** * @file - * Manages content translations. + * Manages content translations. * - * Translations are managed in sets of posts, which represent the same - * information in different languages. Only content types for which the - * administrator explicitly enabled translations could have translations - * associated. Translations are managed in sets with exactly one source - * post per set. The source post is used to translate to different - * languages, so if the source post is significantly updated, the - * editor can decide to mark all translations outdated. + * Translations are managed in sets of posts, which represent the same + * information in different languages. Only content types for which the + * administrator has explicitly enabled translations could have translations + * associated. Translations are managed in sets with exactly one source post + * per set. The source post is used to translate to different languages, so if + * the source post is significantly updated, the editor can decide to mark all + * translations outdated. * - * The node table stores the values used by this module: - * - 'tnid' is the translation set id, which equals the node id - * of the source post. - * - 'translate' is a flag, either indicating that the translation - * is up to date (0) or needs to be updated (1). + * The node table stores the values used by this module: + * - tnid: Integer for the translation set ID, which equals the node ID of the + * source post. + * - translate: Integer indicating that the translation is up to date (0) or + * needs to be updated (1). */ /** @@ -70,11 +70,18 @@ function translation_menu() { } /** - * Menu access callback. + * Access callback: Checks that the user has permission to 'translate content'. * - * Only display translation tab for node types, which have translation enabled - * and where the current node is not language neutral (which should span - * all languages). + * Only displays the translation tab for nodes that are not language-neutral + * of types that have translation enabled. + * + * @param $node + * A node object. + * + * @return + * TRUE if the translation tab should be displayed, FALSE otherwise. + * + * @see translation_menu() */ function _translation_tab_access($node) { if ($node->langcode != LANGUAGE_NOT_SPECIFIED && translation_supported_type($node->type) && node_access('view', $node)) { @@ -107,7 +114,7 @@ function translation_permission() { } /** - * Implements hook_form_FORM_ID_alter(). + * Implements hook_form_FORM_ID_alter() for node_type_form(). */ function translation_form_node_type_form_alter(&$form, &$form_state) { // Add translation option to content type form. @@ -118,10 +125,12 @@ function translation_form_node_type_form_alter(&$form, &$form_state) { } /** - * Implements hook_form_BASE_FORM_ID_alter(). + * Implements hook_form_BASE_FORM_ID_alter() for node_form(). * - * This function alters language fields on node edit forms when a translation is - * about to be created. + * Alters language fields on node edit forms when a translation is about to be + * created. + * + * @see node_form() */ function translation_form_node_form_alter(&$form, &$form_state) { if (translation_supported_type($form['#node']->type)) { @@ -206,9 +215,9 @@ function translation_form_node_form_alter(&$form, &$form_state) { /** * Implements hook_node_view(). * - * Display translation links with language names, if this node is part of - * a translation set. If no language provider is enabled "fall back" to the - * simple links built through the result of translation_node_get_translations(). + * Displays translation links with language names if this node is part of a + * translation set. If no language provider is enabled, "fall back" to simple + * links built through the result of translation_node_get_translations(). */ function translation_node_view($node, $view_mode) { // If the site has no translations or is not multilingual we have no content @@ -378,7 +387,7 @@ function translation_node_update($node) { /** * Implements hook_node_validate(). * - * Ensure that duplicate translations can not be created for the same source. + * Ensures that duplicate translations can't be created for the same source. */ function translation_node_validate($node, $form) { // Only act on translatable nodes with a tnid or translation_source. @@ -402,8 +411,10 @@ function translation_node_predelete($node) { } /** - * Remove a node from its translation set (if any) - * and update the set accordingly. + * Removes a node from its translation set and updates accordingly. + * + * @param $node + * A node object. */ function translation_remove_from_set($node) { if (isset($node->tnid)) { @@ -437,17 +448,18 @@ function translation_remove_from_set($node) { } /** - * Get all nodes in a translation set, represented by $tnid. + * Gets all nodes in a given translation set. * * @param $tnid - * The translation source nid of the translation set, the identifier - * of the node used to derive all translations in the set. + * The translation source nid of the translation set, the identifier of the + * node used to derive all translations in the set. + * * @return - * Array of partial node objects (nid, title, langcode) representing - * all nodes in the translation set, in effect all translations - * of node $tnid, including node $tnid itself. Because these are - * partial nodes, you need to node_load() the full node, if you - * need more properties. The array is indexed by language code. + * Array of partial node objects (nid, title, langcode) representing all + * nodes in the translation set, in effect all translations of node $tnid, + * including node $tnid itself. Because these are partial nodes, you need to + * node_load() the full node, if you need more properties. The array is + * indexed by language code. */ function translation_node_get_translations($tnid) { if (is_numeric($tnid) && $tnid) { @@ -473,21 +485,21 @@ function translation_node_get_translations($tnid) { * Returns whether the given content type has support for translations. * * @return - * Boolean value. + * TRUE if translation is supported, and FALSE if not. */ function translation_supported_type($type) { return variable_get('node_type_language_' . $type, 0) == TRANSLATION_ENABLED; } /** - * Return paths of all translations of a node, based on - * its Drupal path. + * Returns the paths of all translations of a node, based on its Drupal path. * * @param $path * A Drupal path, for example node/432. + * * @return - * An array of paths of translations of the node accessible - * to the current user keyed with language codes. + * An array of paths of translations of the node accessible to the current + * user keyed with language codes. */ function translation_path_get_translations($path) { $paths = array(); diff --git a/core/modules/translation/translation.pages.inc b/core/modules/translation/translation.pages.inc index fd69d34..66dfc42 100644 --- a/core/modules/translation/translation.pages.inc +++ b/core/modules/translation/translation.pages.inc @@ -2,14 +2,19 @@ /** * @file - * User page callbacks for the translation module. + * User page callbacks for the Translation module. */ /** - * Overview page for a node's translations. + * Page callback: Displays a list of a node's translations. * * @param $node - * Node object. + * A node object. + * + * @return + * A render array for a page containing a list of content. + * + * @see translation_menu() */ function translation_node_overview($node) { include_once DRUPAL_ROOT . '/core/includes/language.inc'; diff --git a/core/modules/translation/translation.test b/core/modules/translation/translation.test index b174f3a..5fc9577 100644 --- a/core/modules/translation/translation.test +++ b/core/modules/translation/translation.test @@ -2,9 +2,12 @@ /** * @file - * Tests for translation.module + * Tests for the Translation module. */ +/** + * Functional tests for the Translation module. + */ class TranslationTestCase extends DrupalWebTestCase { protected $book; @@ -54,8 +57,7 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Create a basic page with translation, modify the basic page outdating - * translation, and update translation. + * Creates, modifies, and updates a basic page with a translation. */ function testContentTranslation() { // Create Basic page in English. @@ -147,7 +149,7 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Check that language switch links behave properly. + * Checks that the language switch links behave properly. */ function testLanguageSwitchLinks() { // Create a Basic page in English and its translations in Spanish and @@ -188,7 +190,7 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Test that the language switcher block alterations work as intended. + * Tests that the language switcher block alterations work as intended. */ function testLanguageSwitcherBlockIntegration() { // Enable Italian to have three items in the language switcher block. @@ -251,7 +253,7 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Reset static caches to make the test code match the client site behavior. + * Resets static caches to make the test code match the client site behavior. */ function resetCaches() { drupal_static_reset('language_list'); @@ -260,15 +262,20 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Return an empty node data structure. + * Returns an empty node data structure. + * + * @param $langcode + * The language code. + * + * @return + * An empty node data structure. */ function emptyNode($langcode) { return (object) array('nid' => NULL, 'langcode' => $langcode); } /** - * Install a the specified language if it has not been already. Otherwise make sure that - * the language is enabled. + * Installs the specified language, or enables it if it is already installed. * * @param $language_code * The language code the check. @@ -305,14 +312,17 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Create a "Basic page" in the specified language. + * Creates a "Basic page" in the specified language. * * @param $title - * Title of basic page in specified language. + * The title of the basic page in the specified language. * @param $body - * Body of basic page in specified language. + * The body of the basic page in the specified language. * @param $langcode * (optional) Language code. + * + * @return + * A node object. */ function createPage($title, $body, $langcode = NULL) { $edit = array(); @@ -333,17 +343,19 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Create a translation for the specified basic page in the specified - * language. + * Creates a translation for a basic page in the specified language. * * @param $node - * The basic page to create translation for. + * The basic page to create the translation for. * @param $title - * Title of basic page in specified language. + * The title of a basic page in the specified language. * @param $body - * Body of basic page in specified language. + * The body of a basic page in the specified language. * @param $langcode - * Language code. + * (optional) Language code. + * + * @return + * Translation object. */ function createTranslation($node, $title, $body, $langcode) { $this->drupalGet('node/add/page', array('query' => array('translation' => $node->nid, 'target' => $langcode))); @@ -368,10 +380,10 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Assert that an element identified by the given XPath has the given content. + * Asserts an element identified by the given XPath has the given content. * * @param $xpath - * XPath used to find the element. + * The XPath used to find the element. * @param array $arguments * An array of arguments with keys in the form ':name' matching the * placeholders in the query. The values may be either strings or numeric @@ -379,7 +391,7 @@ class TranslationTestCase extends DrupalWebTestCase { * @param $value * The text content of the matched element to assert. * @param $message - * Message to display. + * The message to display. * @param $group * The group this message belongs to. * @@ -392,7 +404,7 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Check that the specified language switch links are found/not found. + * Tests whether the specified language switch links are found. * * @param $node * The node to display. @@ -404,7 +416,7 @@ class TranslationTestCase extends DrupalWebTestCase { * The page areas to be checked. * * @return - * TRUE if the language switch links are found/not found. + * TRUE if the language switch links are found, FALSE if not. */ function assertLanguageSwitchLinks($node, $translation, $find = TRUE, $types = NULL) { if (empty($types)) { @@ -446,7 +458,19 @@ class TranslationTestCase extends DrupalWebTestCase { } /** - * Search for elements matching the given xpath and value. + * Searches for elements matching the given xpath and value. + * + * @param $xpath + * The XPath used to find the element. + * @param array $arguments + * An array of arguments with keys in the form ':name' matching the + * placeholders in the query. The values may be either strings or numeric + * values. + * @param $value + * The text content of the matched element to assert. + * + * @return + * TRUE if found, otherwise FALSE. */ function findContentByXPath($xpath, array $arguments = array(), $value = NULL) { $elements = $this->xpath($xpath, $arguments);