- New and updated doxygen comments.

3 files changed, 176 insertions, 102 deletions

diff --git a/includes/common.inc b/includes/common.inc
index 2eae306cb..203ede5fc 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -2,7 +2,12 @@
 /* $Id$ */
 
 /**
- * @name drupal_title
+ * @defgroup common Core functions
+ */
+
+/**
+ * @name Page title
+ * @ingroup common
  *
  * Functions to get and set the title of the current page.
  * @{
@@ -25,10 +30,11 @@ function drupal_get_title() {
 
   return $title;
 }
-// @}
+/* @} */
 
 /**
- * @name drupal_message
+ * @name Page messages
+ * @ingroup common
  *
  * Functions to get and set the message of the current page.
  * @{
@@ -46,17 +52,20 @@ function drupal_set_message($message = NULL, $type = "status") {
 function drupal_get_messages() {
   return drupal_set_message();
 }
-// @}
+/* @} */
 
 /**
- * @name drupal_breadcrumb
+ * @name Page breadcrumbs
+ * @ingroup common
  *
  * 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.
  * @{
  */
+
+/**
+ * @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;
 
@@ -76,10 +85,13 @@ function drupal_get_breadcrumb() {
 
   return $breadcrumb;
 }
-// @}
+/* @} */
 
 /**
- * Build the alias/path array
+ * @name URL path
+ * @ingroup common
+ *
+ * Function to handle path aliases.
  */
 function drupal_get_path_map($action = "") {
   static $map = NULL;
@@ -101,7 +113,63 @@ function drupal_get_path_map($action = "") {
 function drupal_rebuild_path_map() {
   drupal_get_path_map("rebuild");
 }
+/* @} */
+
+/**
+ * @name HTTP handling
+ * @ingroup common
+ *
+ * Functions to properly handle HTTP responses.
+ * @{
+ */
+
+/**
+ * HTTP redirects. Makes sure the redirected url is formatted correctly and
+ * includes the session ID.
+ *
+ * @note This function ends the request.
+ *
+ * @param $url A string containing a fully qualified URI.
+ */
+function drupal_goto($url) {
+
+  /*
+  ** Translate & to simply &
+  */
 
+  $url = str_replace("&", "&", $url);
+
+  /*
+  ** It is advised to use "drupal_goto()" instead of PHP's "header()" as
+  ** "drupal_goto()" will append the user's session ID to the URI when PHP
+  ** is compiled with "--enable-trans-sid".
+  */
+  if (!ini_get("session.use_trans_sid") || !session_id() || strstr($url, session_id())) {
+    header("Location: $url");
+  }
+  else {
+    $sid = session_name() . "=" . session_id();
+
+    if (strstr($url, "?") && !strstr($url, $sid)) {
+      header("Location: $url&". $sid);
+    }
+    else {
+      header("Location: $url?". $sid);
+    }
+  }
+
+  /*
+  ** The "Location" header sends a REDIRECT status code to the http
+  ** daemon.  In some cases this can go wrong, so we make sure none
+  ** of the code /below/ gets executed when we redirect.
+  */
+
+  exit();
+}
+
+/**
+ * Generates a 404 error if the request can not be handled.
+ */
 function drupal_not_found() {
   header("HTTP/1.0 404 Not Found");
   watchdog("httpd", "404 error: '". check_query($_GET["q"]) ."' not found");
@@ -119,6 +187,7 @@ function drupal_not_found() {
     print theme("page", '<h1>'. t('Page not found') .'</h1>');
   }
 }
+/* @} */
 
 function error_handler($errno, $message, $filename, $line, $variables) {
   $types = array(1 => "error", 2 => "warning", 4 => "parse error", 8 => "notice", 16 => "core error", 32 => "core warning", 64 => "compile error", 128 => "compile warning", 256 => "user error", 512 => "user warning", 1024 => "user notice");
@@ -161,6 +230,13 @@ function fix_gpc_magic() {
   }
 }
 
+/**
+ * @name Conversion
+ * @ingroup common
+ *
+ * Converts data structures to a different type.
+ * @{
+ */
 function array2object($array) {
   if (is_array($array)) {
     foreach ($array as $key => $value) {
@@ -186,7 +262,15 @@ function object2array($object) {
 
   return $array;
 }
+/* @} */
 
+/**
+ * @name Messages
+ * @ingroup common
+ *
+ * Frequently used messages.
+ * @{
+ */
 function message_access() {
   return t("You are not authorized to access this page.");
 }
@@ -198,6 +282,7 @@ function message_na() {
 function message_throttle() {
   return t("You exceeded the maximum submission rate.  Please wait a few minutes and try again.");
 }
+/* @} */
 
 function locale_init() {
   global $languages, $user;
@@ -209,20 +294,27 @@ function locale_init() {
   }
 }
 
+/**
+ * @ingroup common
+ *
+ * Translates strings to the current locale.
+ *
+ * We try to keep strings whole as much as possible and are unafraid of HTML
+ * markup within translation strings if necessary. The suggested syntax for
+ * a link embedded within a translation string is for example:
+ * @code
+ *   $msg = t("You must login below or \<a href=\"%url\"\>create a new
+ *             account\</a\> before viewing the next page.", array("%url"
+ *             => url("user/register")));
+ * @endcode
+ *
+ * @param $string A string containing the english string to translate.
+ * @param $args Array of values to replace in the string.
+ * @return Translated string.
+ */
 function t($string, $args = 0) {
   global $languages;
 
-  /*
-  ** About the usage of t().  We try to keep strings whole as much as
-  ** possible and are unafraid of HTML markup within translation strings
-  ** if necessary.  The suggested syntax for a link embedded within a
-  ** translation string is for example:
-  **
-  ** $msg = t("You must login below or <a href=\"%url\">create a new
-  **           account</a> before viewing the next page.", array("%url"
-  **           => url("user/register")));
-  */
-
   $string = ($languages && module_exist("locale") ? locale($string) : $string);
 
   if (!$args) {
@@ -246,10 +338,18 @@ function drupal_specialchars($input, $quotes = ENT_NOQUOTES) {
 }
 
 /**
+ * @name Validation
+ * @ingroup common
+ *
+ * Functions to validate user input.
+ */
+
+/**
  * Verify the syntax of the given e-mail address. Empty e-mail addresses are
  * allowed. See RFC 2822 for details.
  *
- * @param $mail a email address
+ * @param $mail A string containing an email address.
+ * @return 
  */
 function valid_email_address($mail) {
   $user = '[a-zA-Z0-9_\-\.\+\^!#\$%&*+\/\=\?\`\|\{\}~\']+';
@@ -269,6 +369,48 @@ function valid_url($url) {
   return preg_match("/^[a-zA-z0-9\/:_\-_\.,]+$/", $url);
 }
 
+function valid_input_data($data) {
+  if (is_array($data) || is_object($data)) {
+    /*
+    ** Form data can contain a number of nested arrays.
+    */
+
+    foreach ($data as $key => $value) {
+      if (!valid_input_data($value)) {
+        return 0;
+      }
+    }
+  }
+  else {
+    /*
+    ** Detect evil input data.
+    */
+
+    // check strings:
+    $match  = preg_match("/\Wjavascript\s*:/i", $data);
+    $match += preg_match("/\Wexpression\s*\(/i", $data);
+    $match += preg_match("/\Walert\s*\(/i", $data);
+
+    // check attributes:
+    $match += preg_match("/\W(dynsrc|datasrc|data|lowsrc|on[a-z]+)\s*=[^>]+?>/i", $data);
+
+    // check tags:
+    $match += preg_match("/<\s*(applet|script|object|style|embed|form|blink|meta|html|frame|iframe|layer|ilayer|head|frameset|xml)/i", $data);
+
+    if ($match) {
+      watchdog("warning", "terminated request because of suspicious input data: ". drupal_specialchars($data));
+      return 0;
+    }
+  }
+
+  return 1;
+}
+/* @} */
+
+/**
+ * @defgroup search Search interface
+ * @{
+ */
 /**
  * Format a single result entry of a search query:
  *
@@ -375,80 +517,7 @@ function search_type($type, $action = NULL, $keys = NULL, $options = NULL) {
 
   return search_form($action, $keys, $options) . "<br />". search_data($keys);
 }
-
-
-function drupal_goto($url) {
-
-  /*
-  ** Translate &amp; to simply &
-  */
-
-  $url = str_replace("&amp;", "&", $url);
-
-  /*
-  ** It is advised to use "drupal_goto()" instead of PHP's "header()" as
-  ** "drupal_goto()" will append the user's session ID to the URI when PHP
-  ** is compiled with "--enable-trans-sid".
-  */
-  if (!ini_get("session.use_trans_sid") || !session_id() || strstr($url, session_id())) {
-    header("Location: $url");
-  }
-  else {
-    $sid = session_name() . "=" . session_id();
-
-    if (strstr($url, "?") && !strstr($url, $sid)) {
-      header("Location: $url&". $sid);
-    }
-    else {
-      header("Location: $url?". $sid);
-    }
-  }
-
-  /*
-  ** The "Location" header sends a REDIRECT status code to the http
-  ** daemon.  In some cases this can go wrong, so we make sure none
-  ** of the code /below/ gets executed when we redirect.
-  */
-
-  exit();
-}
-
-function valid_input_data($data) {
-  if (is_array($data) || is_object($data)) {
-    /*
-    ** Form data can contain a number of nested arrays.
-    */
-
-    foreach ($data as $key => $value) {
-      if (!valid_input_data($value)) {
-        return 0;
-      }
-    }
-  }
-  else {
-    /*
-    ** Detect evil input data.
-    */
-
-    // check strings:
-    $match  = preg_match("/\Wjavascript\s*:/i", $data);
-    $match += preg_match("/\Wexpression\s*\(/i", $data);
-    $match += preg_match("/\Walert\s*\(/i", $data);
-
-    // check attributes:
-    $match += preg_match("/\W(dynsrc|datasrc|data|lowsrc|on[a-z]+)\s*=[^>]+?>/i", $data);
-
-    // check tags:
-    $match += preg_match("/<\s*(applet|script|object|style|embed|form|blink|meta|html|frame|iframe|layer|ilayer|head|frameset|xml)/i", $data);
-
-    if ($match) {
-      watchdog("warning", "terminated request because of suspicious input data: ". drupal_specialchars($data));
-      return 0;
-    }
-  }
-
-  return 1;
-}
+/* @} */
 
 function check_form($text) {
   return drupal_specialchars($text, ENT_QUOTES);
@@ -499,7 +568,7 @@ function format_rss_item($title, $link, $description, $args = array()) {
  * @param $singular The string for the singular case. Please make sure it's
  *   clear this is singular, to ease translation. ("1 new comment" instead of "1
  *   new").
- * @param $plural The string for the plrual case. Please make sure it's clear
+ * @param $plural The string for the plural case. Please make sure it's clear
  *   this is plural, to ease translation. Use %count in places of the item
  *   count, as in "%count new comments".
  */
@@ -605,6 +674,10 @@ function format_name($object) {
   return $output;
 }
 
+/**
+ * @defgroup from Form generation
+ * @{
+ */
 function form($form, $method = "post", $action = 0, $options = 0) {
   if (!$action) {
     $action = request_uri();
@@ -687,6 +760,7 @@ function form_weight($title = NULL, $name = "weight", $value = 0, $delta = 10, $
 function form_allowed_tags_text() {
   return variable_get("allowed_html", "") ? (t("Allowed HTML tags") .": ". htmlspecialchars(variable_get("allowed_html", ""))) : "";
 }
+/* @} */
 
 /**
  * Given an old url, return the alias.
diff --git a/includes/file.inc b/includes/file.inc
index fa0c09a5a..cef043a63 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -2,7 +2,7 @@
 /* $Id$ */
 
 /**
- * @defgroup file File API
+ * @defgroup file File interface
  *   Common file handling functions.
  * @{
  */
diff --git a/includes/pager.inc b/includes/pager.inc
index 871f3348a..0251587e5 100644
--- a/includes/pager.inc
+++ b/includes/pager.inc
@@ -2,7 +2,7 @@
 // $Id$
 
 /**
- * @defgroup pager_api Pager API
+ * @defgroup pager Pager interface
  * @{
  *
  * Pager external functions (API).
@@ -85,9 +85,9 @@ function theme_pager($tags = "", $limit = 10, $element = 0, $attributes = array(
 /** @} End of addtogroup themeable */
 
 /**
- * @name pager pieces Use these pieces to construct your own custom pagers in
- *   your theme. Note that you should NOT modify this file to customize your
- *   pager.
+ * @name Pager pieces
+ *   Use these pieces to construct your own custom pagers in your theme. Note
+ *   that you should NOT modify this file to customize your pager.
  * @{
  */