Issue #1431630 by NROTC_Webmaster, tim.plunkett: Clean up API docs for themes directory

core/themes/bartik/bartik.info

-
 name = Bartik
 description = A flexible, recolorable theme with many regions.
 package = Core
@@ -32,4 +31,3 @@ regions[footer_fourthcolumn] = Footer fourth column
 regions[footer] = Footer
 
 settings[shortcut_module_link] = 0
-

core/themes/bartik/color/color.inc

 <?php
 
+/**
+ * @file
+ * Lists avalable colors and color schemes for the Bartik theme.
+ */
+
 // Put the logo path into JavaScript for the live preview.
 drupal_add_js(array('color' => array('logo' => theme_get_setting('logo', 'bartik'))), 'setting');
 

core/themes/bartik/color/preview.js

+/**
+ * @file
+ * Preview for the Bartik theme.
+ */
+
 (function ($) {
   Drupal.color = {
     logoChanged: false,
@@ -7,7 +12,7 @@
         $('#preview #preview-logo img').attr('src', Drupal.settings.color.logo);
         this.logoChanged = true;
       }
-      // Remove the logo if the setting is toggled off. 
+      // Remove the logo if the setting is toggled off.
       if (Drupal.settings.color.logo == null) {
         $('div').remove('#preview-logo');
       }

core/themes/bartik/template.php

 <?php
 
 /**
- * Add body classes if certain regions have content.
+ * @file
+ * Functions to support theming in the Bartik theme.
+ */
+
+/**
+ * Implements hook_preprocess_HOOK() for html.tpl.php.
+ *
+ * Adds body classes if certain regions have content.
  */
 function bartik_preprocess_html(&$variables) {
   if (!empty($variables['page']['featured'])) {
@@ -23,7 +30,7 @@ function bartik_preprocess_html(&$variables) {
 }
 
 /**
- * Override or insert variables into the page template for HTML output.
+ * Implements hook_process_HOOK() for html.tpl.php.
  */
 function bartik_process_html(&$variables) {
   // Hook into color.module.
@@ -33,7 +40,7 @@ function bartik_process_html(&$variables) {
 }
 
 /**
- * Override or insert variables into the page template.
+ * Implements hook_process_HOOK() for page.tpl.php.
  */
 function bartik_process_page(&$variables) {
   // Hook into color.module.
@@ -70,7 +77,7 @@ function bartik_process_page(&$variables) {
 }
 
 /**
- * Implements hook_preprocess_maintenance_page().
+ * Implements hook_preprocess_HOOK() for maintenance-page.tpl.php.
  */
 function bartik_preprocess_maintenance_page(&$variables) {
   // By default, site_name is set to Drupal if no db connection is available
@@ -84,7 +91,7 @@ function bartik_preprocess_maintenance_page(&$variables) {
 }
 
 /**
- * Override or insert variables into the maintenance page template.
+ * Implements hook_process_HOOK() for maintenance-page.tpl.php.
  */
 function bartik_process_maintenance_page(&$variables) {
   // Always print the site name and slogan, but if they are toggled off, we'll
@@ -102,7 +109,7 @@ function bartik_process_maintenance_page(&$variables) {
 }
 
 /**
- * Override or insert variables into the block template.
+ * Implements hook_preprocess_HOOK() for block.tpl.php.
  */
 function bartik_preprocess_block(&$variables) {
   // In the header region visually hide block titles.

core/themes/bartik/templates/comment-wrapper.tpl.php

@@ -33,6 +33,8 @@
  *
  * @see template_preprocess_comment_wrapper()
  * @see theme_comment_wrapper()
+ *
+ * @ingroup themeable
  */
 ?>
 <div id="comments" class="<?php print $classes; ?>"<?php print $attributes; ?>>

core/themes/bartik/templates/comment.tpl.php

@@ -5,9 +5,9 @@
  * Bartik's theme implementation for comments.
  *
  * Available variables:
- * - $author: Comment author. Can be link or plain text.
- * - $content: An array of comment items. Use render($content) to print them all, or
- *   print a subset such as render($content['field_example']). Use
+ * - $author: Comment author. Can be a link or plain text.
+ * - $content: An array of comment items. Use render($content) to print them
+ *   all, or print a subset such as render($content['field_example']). Use
  *   hide($content['field_example']) to temporarily suppress the printing of a
  *   given element.
  * - $created: Formatted date and time for when the comment was created.
@@ -18,8 +18,8 @@
  *   desired parameters on the $comment->changed variable.
  * - $new: New comment marker.
  * - $permalink: Comment permalink.
- * - $submitted: Submission information created from $author and $created during
- *   template_preprocess_comment().
+ * - $submitted: Submission information created from $author and $created
+ *   during template_preprocess_comment().
  * - $picture: Authors picture.
  * - $signature: Authors signature.
  * - $status: Comment status. Possible values are:
@@ -27,7 +27,8 @@
  * - $title: Linked title.
  * - $classes: String of classes that can be used to style contextually through
  *   CSS. It can be manipulated through the variable $classes_array from
- *   preprocess functions. The default values can be one or more of the following:
+ *   preprocess functions. The default values can be one or more of the
+ *   following:
  *   - comment: The current template type; e.g., 'theming hook'.
  *   - by-anonymous: Comment by an unregistered user.
  *   - by-node-author: Comment by the author of the parent node.
@@ -55,6 +56,8 @@
  * @see template_preprocess_comment()
  * @see template_process()
  * @see theme_comment()
+ *
+ * @ingroup themeable
  */
 ?>
 <div class="<?php print $classes; ?> clearfix"<?php print $attributes; ?>>

core/themes/bartik/templates/maintenance-page.tpl.php

@@ -2,13 +2,15 @@
 
 /**
  * @file
- * Implementation to display a single Drupal page while offline.
+ * Bartik's theme implementation to display a single Drupal page while offline.
  *
- * All the available variables are mirrored in page.tpl.php.
+ * All of the available variables are mirrored in page.tpl.php.
  *
  * @see template_preprocess()
  * @see template_preprocess_maintenance_page()
  * @see bartik_process_maintenance_page()
+ *
+ * @ingroup themeable
  */
 ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"

core/themes/bartik/templates/node.tpl.php

@@ -12,7 +12,8 @@
  *   given element.
  * - $user_picture: The node author's picture from user-picture.tpl.php.
  * - $date: Formatted creation date. Preprocess functions can reformat it by
- *   calling format_date() with the desired parameters on the $created variable.
+ *   calling format_date() with the desired parameters on the $created
+ *   variable.
  * - $name: Themed username of node author output from theme_username().
  * - $node_url: Direct url of the current node.
  * - $display_submitted: Whether submission information should be displayed.
@@ -66,16 +67,18 @@
  * - $logged_in: Flags true when the current user is a logged-in member.
  * - $is_admin: Flags true when the current user is an administrator.
  *
- * Field variables: for each field instance attached to the node a corresponding
- * variable is defined, e.g. $node->body becomes $body. When needing to access
- * a field's raw values, developers/themers are strongly encouraged to use these
- * variables. Otherwise they will have to explicitly specify the desired field
- * language, e.g. $node->body['en'], thus overriding any language negotiation
- * rule that was previously applied.
+ * Field variables: For each field instance attached to the node a
+ * corresponding variable is defined, e.g. $node->body becomes $body. When
+ * needing to access a field's raw values, developers/themers are strongly
+ * encouraged to use these variables. Otherwise they will have to explicitly
+ * specify the desired field language, e.g. $node->body['en'], thus overriding
+ * any language negotiation rule that was previously applied.
  *
  * @see template_preprocess()
  * @see template_preprocess_node()
  * @see template_process()
+ *
+ * @ingroup themeable
  */
 ?>
 <div id="node-<?php print $node->nid; ?>" class="<?php print $classes; ?> clearfix"<?php print $attributes; ?>>

core/themes/bartik/templates/page.tpl.php

@@ -4,8 +4,8 @@
  * @file
  * Bartik's theme implementation to display a single Drupal page.
  *
- * The doctype, html, head and body tags are not in this template. Instead they
- * can be found in the html.tpl.php template normally located in the
+ * The doctype, html, head, and body tags are not in this template. Instead
+ * they can be found in the html.tpl.php template normally located in the
  * core/modules/system directory.
  *
  * Available variables:
@@ -54,8 +54,8 @@
  *   prominently.
  * - $tabs (array): Tabs linking to any sub-pages beneath the current page
  *   (e.g., the view and edit tabs when displaying a node).
- * - $action_links (array): Actions local to the page, such as 'Add menu' on the
- *   menu administration interface.
+ * - $action_links (array): Actions local to the page, such as 'Add menu' on
+ *   the menu administration interface.
  * - $feed_icons: A string of all feed icons for the current page.
  * - $node: The node object, if there is an automatically-loaded node
  *   associated with the page, and the node ID is the second argument
@@ -83,6 +83,8 @@
  * @see template_process()
  * @see bartik_process_page()
  * @see html.tpl.php
+ *
+ * @ingroup themeable
  */
 ?>
 <div id="page-wrapper"><div id="page">

core/themes/seven/maintenance-page.tpl.php

+<?php
+
+/**
+ * @file
+ * Seven's theme implementation to display a single Drupal page while offline.
+ *
+ * All of the available variables are mirrored in page.tpl.php.
+ *
+ * @see template_preprocess()
+ * @see template_preprocess_maintenance_page()
+ * @see seven_preprocess_maintenance_page()
+ *
+ * @ingroup themeable
+ */
+?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php print $language->langcode ?>" lang="<?php print $language->langcode ?>" dir="<?php print $language->dir ?>">

core/themes/seven/page.tpl.php

+<?php
 
+/**
+ * @file
+ * Seven's theme implementation to display a single Drupal page.
+ *
+ * The doctype, html, head, and body tags are not in this template. Instead
+ * they can be found in the html.tpl.php template normally located in the
+ * core/modules/system directory.
+ *
+ * @see template_preprocess()
+ * @see template_preprocess_page()
+ * @see template_process()
+ * @see seven_preprocess_page()
+ *
+ * @ingroup themeable
+ */
+?>
   <div id="branding" class="clearfix">
     <?php print $breadcrumb; ?>
     <?php print render($title_prefix); ?>

core/themes/seven/template.php

 <?php
 
 /**
- * Override or insert variables into the maintenance page template.
+ * @file
+ * Functions to support theming in the Seven theme.
+ */
+
+/**
+ * Implements hook_preprocess_HOOK() for maintenance-page.tpl.php.
  */
 function seven_preprocess_maintenance_page(&$vars) {
   // While markup for normal pages is split into page.tpl.php and html.tpl.php,
@@ -13,7 +18,7 @@ function seven_preprocess_maintenance_page(&$vars) {
 }
 
 /**
- * Override or insert variables into the html template.
+ * Implements hook_preprocess_HOOK() for html.tpl.php.
  */
 function seven_preprocess_html(&$vars) {
   // Add conditional CSS for IE8 and below.
@@ -21,7 +26,7 @@ function seven_preprocess_html(&$vars) {
 }
 
 /**
- * Override or insert variables into the page template.
+ * Implements hook_preprocess_HOOK() for page.tpl.php.
  */
 function seven_preprocess_page(&$vars) {
   $vars['primary_local_tasks'] = $vars['tabs'];
@@ -33,7 +38,7 @@ function seven_preprocess_page(&$vars) {
 }
 
 /**
- * Display the list of available node types for node creation.
+ * Displays the list of available node types for node creation.
  */
 function seven_node_add_list($variables) {
   $content = $variables['content'];
@@ -57,7 +62,7 @@ function seven_node_add_list($variables) {
 /**
  * Overrides theme_admin_block_content().
  *
- * Use unordered list markup in both compact and extended mode.
+ * Uses an unordered list markup in both compact and extended mode.
  */
 function seven_admin_block_content($variables) {
   $content = $variables['content'];
@@ -78,9 +83,10 @@ function seven_admin_block_content($variables) {
 }
 
 /**
- * Override of theme_tablesort_indicator().
+ * Overrides theme_tablesort_indicator().
  *
- * Use our own image versions, so they show up as black and not gray on gray.
+ * Uses Seven's image versions, so the arrows show up as black and not gray on
+ * gray.
  */
 function seven_tablesort_indicator($variables) {
   $style = $variables['style'];

core/themes/stark/README.txt

@@ -2,17 +2,17 @@
 ABOUT STARK
 -----------
 
-The Stark theme is provided for demonstration purposes; it uses Drupal's default
-HTML markup and CSS styles. It can be used as a troubleshooting tool to
+The Stark theme is provided for demonstration purposes; it uses Drupal's
+default HTML markup and CSS styles. It can be used as a troubleshooting tool to
 determine whether module-related CSS and JavaScript are interfering with a more
 complex theme, and can be used by designers interested in studying Drupal's
-default markup without the interference of changes commonly made by more complex
-themes.
+default markup without the interference of changes commonly made by more
+complex themes.
 
 To avoid obscuring CSS added to the page by Drupal or a contrib module, the
-Stark theme itself has no styling, except just enough CSS to arrange the page in
-a traditional "Header, sidebars, content, and footer" layout. See the layout.css
-file for more information.
+Stark theme itself has no styling, except just enough CSS to arrange the page
+in a traditional "Header, sidebars, content, and footer" layout. See the
+layout.css file for more information.
 
 
 ABOUT DRUPAL THEMING

core/themes/stark/template.php

 <?php
 
 /**
- * Override or insert variables into the html template.
+ * @file
+ * Functions to support theming in the Stark theme.
+ */
+
+/**
+ * Implements hook_preprocess_HOOK() for html.tpl.php.
  *
  * @todo Based on outcome of http://drupal.org/node/1471382, revise this
  *   technique to use conditional classes vs. conditional stylesheets.