Issue #1431632 by NROTC_Webmaster: Clean up API docs for translation module

3 files changed, 110 insertions, 69 deletions

diff --git a/modules/translation/translation.module b/modules/translation/translation.module
index 794bd35f5..b353aa4ec 100644
--- a/modules/translation/translation.module
+++ b/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 flag, either 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->language != LANGUAGE_NONE && 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.
@@ -117,10 +124,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)) {
@@ -200,9 +209,9 @@ function translation_form_node_form_alter(&$form, &$form_state) {
 /**
  * Implements hook_node_view().
  *
- * Display translation links with native 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
@@ -373,7 +382,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.
@@ -397,8 +406,10 @@ function translation_node_delete($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)) {
@@ -432,17 +443,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, language) 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, language) 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) {
@@ -468,21 +480,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('language_content_type_' . $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/modules/translation/translation.pages.inc b/modules/translation/translation.pages.inc
index 7e4f0af26..fa4070bb8 100644
--- a/modules/translation/translation.pages.inc
+++ b/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 . '/includes/language.inc';
diff --git a/modules/translation/translation.test b/modules/translation/translation.test
index 48546a17d..09bc9e3b9 100644
--- a/modules/translation/translation.test
+++ b/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;
 
@@ -58,8 +61,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.
@@ -151,7 +153,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
@@ -192,7 +194,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.
@@ -254,25 +256,30 @@ 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-side behavior.
    */
   function resetCaches() {
     drupal_static_reset('locale_url_outbound_alter');
   }
 
   /**
-   * 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, 'language' => $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.
+   *   The language code to check.
    */
   function addLanguage($language_code) {
     // Check to make sure that language has not already been installed.
@@ -306,14 +313,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 a basic page in the specified language.
    * @param $body
-   *   Body of basic page in specified language.
-   * @param
-   *   $language Language code.
+   *   The body of a basic page in the specified language.
+   * @param $language
+   *   (optional) Language code.
+   *
+   * @return
+   *   A node object.
    */
   function createPage($title, $body, $language = NULL) {
     $edit = array();
@@ -334,17 +344,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 $language
    *   Language code.
+   *
+   * @return
+   *   Translation object.
    */
   function createTranslation($node, $title, $body, $language) {
     $this->drupalGet('node/add/page', array('query' => array('translation' => $node->nid, 'target' => $language)));
@@ -369,10 +381,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
@@ -380,7 +392,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.
    *
@@ -393,7 +405,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.
@@ -405,7 +417,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)) {
@@ -447,7 +459,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);