- Doxygen improvements. Patch by Ax.

2 files changed, 160 insertions, 143 deletions

diff --git a/includes/common.inc b/includes/common.inc
index 1cf0b3c61..04026a81e 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -2,10 +2,11 @@
 // $Id$
 
 /**
- * @name drupal_title
- * Functions to get and set the title of the current page.
- * @{
- */
+  @name drupal_title
+
+  Functions to get and set the title of the current page.
+  @{
+**/
 function drupal_set_title($title = NULL) {
   static $stored_title;
 
@@ -27,12 +28,14 @@ function drupal_get_title() {
 // @}
 
 /**
- * @name drupal_breadcrumb
- * Functions to get and set the breadcrumb trail of the current page. The
- * breadcrumb trail is represented as an array of links, starting with
- * "home" and proceeding up to but not including the current page.
- * @{
- */
+  @name drupal_breadcrumb
+
+  Functions to get and set the breadcrumb trail of the current page.
+
+  @param   $breadcrumb   array of links, starting with "home" and proceeding
+    up to but not including the current page.
+  @{
+**/
 function drupal_set_breadcrumb($breadcrumb = NULL) {
   static $stored_breadcrumb;
 
@@ -55,8 +58,8 @@ function drupal_get_breadcrumb() {
 // @}
 
 /**
- * Build the alias/path array
- */
+  Build the alias/path array
+**/
 function drupal_get_path_map($action = "") {
 
   static $cache;
diff --git a/includes/theme.inc b/includes/theme.inc
index 505c727f4..f0790159a 100644
--- a/includes/theme.inc
+++ b/includes/theme.inc
@@ -1,17 +1,130 @@
 <?php
+/* $Id$ */
+
 /**
-  Theme System - controls the output of Drupal.
+ @file
 
-  The theme system allows for nearly all output of the Drupal system to be
-  customized by user themes.
+ Theme System - controls the output of Drupal.
 
-  @package theme_system
+ The theme system allows for nearly all output of the Drupal system to be
+ customized by user themes.
 
-  @defgroup theme_system
-  @{
+ @see <a href="http://drupal.org/node/view/253">Theme system</a>
+ @see themeable
 **/
 
-/* $Id$ */
+/**
+  Hook Help - returns theme specific help and information.
+
+  @param section defines the \a section of the help to be returned.
+
+  @return a string containing the help output.
+**/
+function theme_help($section) {
+  $ouptout = "";
+
+  switch ($section) {
+    case 'admin/system/themes#description':
+      $output = t("The base theme");
+      break;
+  }
+  return $output;
+}
+
+/**
+  Initialized the theme system.
+
+  @return the name of the currently selected theme.
+**/
+function init_theme() {
+  global $user;
+
+  $themes = list_themes();
+  $name = $user->theme ? $user->theme : variable_get("theme_default", 0);
+
+  $theme->path = "";
+  $theme->name = "";
+
+  if (is_object($themes[$name])) {
+    include_once($themes[$name]->filename);
+    $theme->path = dirname($themes[$name]->filename);
+    $theme->name = $name;
+  }
+
+  return $theme;
+}
+
+/**
+  Provides a list of currently available themes.
+
+  @param $refresh
+
+  @return an array of the currently available themes.
+**/
+function list_themes($refresh = 0) {
+  static $list;
+
+  if ($refresh) {
+    unset($list);
+  }
+
+  if (!$list) {
+    $list = array();
+    $result = db_query("SELECT * FROM {system} where type = 'theme' AND status = '1' ORDER BY name");
+    while ($theme = db_fetch_object($result)) {
+      if (file_exists($theme->filename)) {
+        $list[$theme->name] = $theme;
+      }
+    }
+  }
+
+  return $list;
+}
+
+/**
+  External interface of the theme system to all other modules, and core files.
+
+  All requests for themed functions must go through this function. It examines
+  the request and routes it to the appropriate theme function. If the current
+  theme does not implement the requested function, then the base theme function
+  is called.
+  Example: \verbatim $header_text = theme("header"); \endverbatim
+
+  @return themed output.
+**/
+function theme() {
+  global $theme;
+
+  $args = func_get_args();
+  $function = array_shift($args);
+
+  if (($theme->name != "") && (function_exists($theme->name ."_". $function))) {
+    return call_user_func_array($theme->name ."_". $function, $args);
+  }
+  elseif (function_exists("theme_". $function)){
+    return call_user_func_array("theme_". $function, $args);
+  }
+}
+
+/**
+  Returns the path to the currently selected theme.
+
+  @return the path to the the currently selected theme.
+**/
+function path_to_theme() {
+  global $theme;
+  return $theme->path;
+}
+
+/**
+  @defgroup themeable Themeable Functions
+  @{
+
+  Themeable Functions - functions that can be styled differently in themes.
+
+  @see  theme
+  @see  theme.inc
+**/
 
 /**
   Returns the theme header.
@@ -48,10 +161,15 @@ function theme_header() {
 }
 
 /**
-  Returns an entire Drupal page displaying the supplied content.
-  @param $content a string containing the content to display.
-
-  @return a string containing the \a page output.
+ * Returns an entire Drupal page displaying the supplied content.
+ *
+ * @param $content    a string containing the content to display
+ * @param $title      (optional) page title (\<head>\<title>)
+ * @param $breadcrumb (optional) page breadcrumb
+ *
+ * @see   drupal_breadcrumb
+ *
+ * @return a string containing the \a page output.
 **/
 function theme_page($content, $title = NULL, $breadcrumb = NULL) {
   if (isset($title)) {
@@ -153,29 +271,6 @@ function theme_node($node, $main = 0, $page = 0) {
   return $output;
 }
 
-function _theme_table_cell($cell, $header = 0) {
-  if (is_array($cell)) {
-    $data = $cell["data"];
-    foreach ($cell as $key => $value) {
-      if ($key != "data")  {
-        $attributes .= " $key=\"$value\"";
-      }
-    }
-  }
-  else {
-    $data = $cell;
-  }
-
-  if ($header) {
-    $output = "<th$attributes>$data</th>";
-  }
-  else {
-    $output = "<td$attributes>$data</td>";
-  }
-
-  return $output;
-}
-
 /**
   Returns themed table.
 
@@ -356,7 +451,7 @@ function theme_head($main = 0) {
 
 /**
   Execute hook _footer() which is run at the end of the page right
-  before the </body> tag.
+  before the \</body> tag.
 
   @param $main (optional)
 
@@ -406,109 +501,28 @@ function theme_blocks($region) {
   }
   return $output;
 }
+/* @} End of defgroup themeable */
 
-/**
-  Hook Help - returns theme specific help and information.
-
-  @param section defines the \a section of the help to be returned.
-
-  @return a string containing the help output.
-**/
-function theme_help($section) {
-  $ouptout = "";
-
-  switch ($section) {
-    case 'admin/system/themes#description':
-      $output = t("The base theme");
-      break;
-  }
-  return $output;
-}
-
-/**
-  Provides a list of currently available themes.
-
-  @param $refresh
-
-  @return an array of the currently available themes.
-**/
-function list_themes($refresh = 0) {
-  static $list;
-
-  if ($refresh) {
-    unset($list);
-  }
-
-  if (!$list) {
-    $list = array();
-    $result = db_query("SELECT * FROM {system} where type = 'theme' AND status = '1' ORDER BY name");
-    while ($theme = db_fetch_object($result)) {
-      if (file_exists($theme->filename)) {
-        $list[$theme->name] = $theme;
+function _theme_table_cell($cell, $header = 0) {
+  if (is_array($cell)) {
+    $data = $cell["data"];
+    foreach ($cell as $key => $value) {
+      if ($key != "data")  {
+        $attributes .= " $key=\"$value\"";
       }
     }
   }
-
-  return $list;
-}
-
-/**
-  Initialized the theme system.
-
-  @return the name of the currently selected theme.
-**/
-function init_theme() {
-  global $user;
-
-  $themes = list_themes();
-  $name = $user->theme ? $user->theme : variable_get("theme_default", 0);
-
-  $theme->path = "";
-  $theme->name = "";
-
-  if (is_object($themes[$name])) {
-    include_once($themes[$name]->filename);
-    $theme->path = dirname($themes[$name]->filename);
-    $theme->name = $name;
+  else {
+    $data = $cell;
   }
 
-  return $theme;
-}
-
-/**
-  Returns the path to the currently selected theme.
-
-  @return the path to the the currently selected theme.
-**/
-function path_to_theme() {
-  global $theme;
-  return $theme->path;
-}
-
-/**
-  External interface of the theme system to all other modules, and core files.
-
-  All requests for themed functions must go through this function. It examines
-  the request and routes it to the appropriate theme function. If the current
-  theme does not implement the requested function, then the base theme function
-  is called.
-  Example: \verbatim $header_text = theme("header"); \endverbatim
-
-  @return the path to the the currently selected theme.
-**/
-function theme() {
-  global $theme;
-
-  $args = func_get_args();
-  $function = array_shift($args);
-
-  if (($theme->name != "") && (function_exists($theme->name ."_". $function))) {
-    return call_user_func_array($theme->name ."_". $function, $args);
+  if ($header) {
+    $output = "<th$attributes>$data</th>";
   }
-  elseif (function_exists("theme_". $function)){
-    return call_user_func_array("theme_". $function, $args);
+  else {
+    $output = "<td$attributes>$data</td>";
   }
-}
 
-/**  @} End of defgroup theme_system **/
+  return $output;
+}
 ?>