#166071 by jjeff and dvessel: move default template preprocess code to template_preprocess, and add *lots* of documentation to template files and functions

3 files changed, 80 insertions, 13 deletions

diff --git a/modules/node/node.tpl.php b/modules/node/node.tpl.php
index 8813f35fc..a2b8c021d 100644
--- a/modules/node/node.tpl.php
+++ b/modules/node/node.tpl.php
@@ -1,11 +1,58 @@
 <?php
 // $Id$
+
+/**
+ * @file node.tpl.php
+ *
+ * Theme implementation to display a node.
+ *
+ * Available variables:
+ * - $title: the (sanitized) title of the node.
+ * - $content: Node body or teaser depending on $teaser flag.
+ * - $picture: The authors picture of the node output from
+ *   theme_user_picture().
+ * - $date: Formatted creation date (use $created to reformat with
+ *   format_date()).
+ * - $links: Themed links like "Read more", "Add new comment", etc. output
+ *   from theme_links().
+ * - $name: Themed username of node author output from theme_user().
+ * - $node_url: Direct url of the current node.
+ * - $terms: the themed list of taxonomy term links output from theme_links().
+ * - $submitted: themed submission information output from
+ *   theme_node_submitted().
+ *
+ * Other variables:
+ * - $node: Full node object. Contains data that may not be safe.
+ * - $type: Node type, i.e. story, page, blog, etc.
+ * - $comment_count: Number of comments attached to the node.
+ * - $uid: User ID of the node author.
+ * - $created: Time the node was published formatted in Unix timestamp.
+ * - $zebra: Outputs either "even" or "odd". Useful for zebra striping in
+ *   teaser listings.
+ * - $id: Position of the node. Increments each time it's output.
+ *
+ * Node status variables:
+ * - $teaser: Flag for the teaser state.
+ * - $page: Flag for the full page state.
+ * - $promote: Flag for front page promotion state.
+ * - $sticky: Flags for sticky post setting.
+ * - $status: Flag for published status.
+ * - $comment: State of comment settings for the node.
+ * - $readmore: Flags true if the teaser content of the node cannot hold the
+ *   main body content.
+ * - $is_front: Flags true when presented in the front page.
+ * - $logged_in: Flags true when the current user is a logged-in member.
+ * - $is_admin: Flags true when the current user is an administrator.
+ *
+ * @see template_preprocess()
+ * @see template_preprocess_node()
+ */
 ?>
 <div id="node-<?php print $node->nid; ?>" class="node<?php if ($sticky) { print ' sticky'; } ?><?php if (!$status) { print ' node-unpublished'; } ?> clear-block">
 
 <?php print $picture ?>
 
-<?php if ($page == 0): ?>
+<?php if (!$page): ?>
   <h2><a href="<?php print $node_url ?>" title="<?php print $title ?>"><?php print $title ?></a></h2>
 <?php endif; ?>
 
@@ -23,10 +70,5 @@
     <?php print $content ?>
   </div>
 
-<?php
-  if ($links) {
-    print $links;
-  }
-?>
-
+  <?php print $links; ?>
 </div>
\ No newline at end of file
diff --git a/modules/system/block.tpl.php b/modules/system/block.tpl.php
index 52bf62b10..3b60cf9f0 100644
--- a/modules/system/block.tpl.php
+++ b/modules/system/block.tpl.php
@@ -1,11 +1,38 @@
 <?php
 // $Id$
+
+/**
+ * @file block.tpl.php
+ *
+ * Theme implementation to display a block.
+ *
+ * Available variables:
+ * - $block->subject: Block title.
+ * - $block->content: Block content.
+ * - $block->module: Module that generated the block.
+ * - $block->delta: This is a numeric id connected to each module.
+ * - $block->region: The block region embedding the current block.
+ *
+ * Helper variables:
+ * - $block_zebra: Outputs 'odd' and 'even' dependent on the default sidebar
+ *   block regions.
+ * - $zebra: Same output as $block_zebra but independent of any block region.
+ * - $block_id: counter within the default sidebar block regions.
+ * - $id: Same output as $block_id but independent of any block region.
+ * - $is_front: Flags true when presented in the front page.
+ * - $logged_in: Flags true when the current user is a logged-in member.
+ * - $is_admin: Flags true when the current user is an administrator.
+ *
+ * @see template_preprocess()
+ * @see template_preprocess_block()
+ */
 ?>
 <div id="block-<?php print $block->module .'-'. $block->delta; ?>" class="block block-<?php print $block->module ?>">
-
 <?php if ($block->subject): ?>
   <h2><?php print $block->subject ?></h2>
 <?php endif;?>
 
-  <div class="content"><?php print $block->content ?></div>
+  <div class="content">
+    <?php print $block->content ?>
+  </div>
 </div>
diff --git a/modules/system/page.tpl.php b/modules/system/page.tpl.php
index a71b18d8f..d6ee32686 100644
--- a/modules/system/page.tpl.php
+++ b/modules/system/page.tpl.php
@@ -14,7 +14,7 @@
  * - $css: An array of CSS files for the current page.
  * - $directory: The directory the theme is located in, e.g. themes/garland or
  *   themes/garland/minelli.
- * - $is_front: TRUE if the current page is the front page.
+ * - $is_front: TRUE if the current page is the front page. Used to toggle the mission statement.
  * - $logged_in: TRUE if the user is registered and signed in.
  * - $is_admin: TRUE if the user has permission to access administration pages.
  *
@@ -30,8 +30,6 @@
  * - $body_classes: A set of CSS classes for the BODY tag. This contains flags
  *   indicating the current layout (multiple columns, single column), the current
  *   path, whether the user is logged in, and so on.
- * - $is_front: True if the front page is currently being displayed. Used to
- *   toggle the mission.
  *
  * Site identity:
  * - $logo: The path to the logo image, as defined in theme configuration.
@@ -69,8 +67,8 @@
  * - $closure: Final closing markup from any modules that have altered the page.
  *   This variable should always be output last, after all other dynamic content.
  *
+ * @see template_preprocess()
  * @see template_preprocess_page()
- * @see phptemplate_engine_preprocess()
  */
 ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"