From a43be88ed3fa40207d9f766a5a0539d5682e1ee2 Mon Sep 17 00:00:00 2001
From: Johan Falk <johan.falk@nodeone.se>
Date: Fri, 11 Mar 2011 16:17:29 +0100
Subject: [PATCH] Issue #1045392: Commenting and some clarifications to translation.pages.inc.

---
 modules/translation/translation.pages.inc |   48 +++++++++++++++++++++-------
 1 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/modules/translation/translation.pages.inc b/modules/translation/translation.pages.inc
index ad0fac0..3812df2 100644
--- a/modules/translation/translation.pages.inc
+++ b/modules/translation/translation.pages.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * User page callbacks for the translation module.
+ * Page callback for the node translation overview page.
  */
 
 /**
@@ -12,47 +12,71 @@
  *   Node object.
  */
 function translation_node_overview($node) {
+  // Set the page title.
+  drupal_set_title(t('Translations of %title', array('%title' => $node->title)));
+
+  // Grab the translation set and the translations for the node.
   if ($node->tnid) {
-    // Already part of a set, grab that set.
+    // If the node is already part of a set, grab that set.
     $tnid = $node->tnid;
     $translations = translation_node_get_translations($node->tnid);
   }
   else {
-    // We have no translation source nid, this could be a new set, emulate that.
+    // If we have no translation set, emulate that this is the source node.
     $tnid = $node->nid;
     $translations = array($node->language => $node);
   }
 
+  // Start building a table holding translation information and links.
   $header = array(t('Language'), t('Title'), t('Status'), t('Operations'));
 
+  // Build one row for each enabled language on the website.
   foreach (language_list() as $language) {
     $options = array();
     $language_name = $language->name;
+
     if (isset($translations[$language->language])) {
-      // Existing translation in the translation set: display status.
-      // We load the full node to check whether the user can edit it.
+      // For existing translation in the translation set: display their status.
+      // We load the full node to check whether the user can edit it, and also
+      // for a number of other checks of node data.
       $translation_node = node_load($translations[$language->language]->nid);
+
+      // Set the language in strong style if it is the source language.
+      if ($translation_node->nid == $tnid) {
+        $language_name = t('<strong>@language_name</strong> (source)',
+          array('@language_name' => $language_name));
+      }
+
+      // Set the node title, linking to its page.
       $title = l($translation_node->title, 'node/'. $translation_node->nid);
+
+      // Set an edit link as an option, if the user can edit the node.
       if (node_access('update', $translation_node)) {
         $options[] = l(t('edit'), "node/$translation_node->nid/edit");
       }
+
+      // Set published status and also mark if translation needs update.
       $status = $translation_node->status ? t('Published') : t('Not published');
-      $status .= $translation_node->translate ? ' - <span class="marker">'. t('outdated') .'</span>' : '';
-      if ($translation_node->nid == $tnid) {
-        $language_name = t('<strong>@language_name</strong> (source)', array('@language_name' => $language_name));
-      }
+      $status .= $translation_node->translate ?
+        ' - <span class="marker">'. t('outdated') .'</span>' : '';
     }
+
     else {
-      // No such translation in the set yet: help user to create it.
+      // If the current node isn't translated to the language on this row.
       $title = t('n/a');
+
+      // Set a link to create a translation, if the user has access to do so.
       if (node_access('create', $node)) {
-        $options[] = l(t('add translation'), 'node/add/'. str_replace('_', '-', $node->type), array('query' => "translation=$node->nid&language=$language->language"));
+        $options[] = l(t('add translation'), 'node/add/'. str_replace('_', '-', $node->type),
+            array('query' => "translation=$node->nid&language=$language->language"));
       }
       $status = t('Not translated');
     }
+
+    // Set a table row for this language, with all data collected above.
     $rows[] = array($language_name, $title, $status, implode(" | ", $options));
   }
 
-  drupal_set_title(t('Translations of %title', array('%title' => $node->title)));
+  // Return a themed table with all the data collected above.
   return theme('table', $header, $rows);
 }
-- 
1.7.1