#197314 by vitezslav.smid (as GHOP 39): improve/add/update phpdoc in aggregator, comment and system modules

11 files changed, 600 insertions, 105 deletions

diff --git a/modules/aggregator/aggregator.admin.inc b/modules/aggregator/aggregator.admin.inc
index dbcb1928d..31e97d45c 100644
--- a/modules/aggregator/aggregator.admin.inc
+++ b/modules/aggregator/aggregator.admin.inc
@@ -13,6 +13,12 @@ function aggregator_admin_overview() {
   return aggregator_view();
 }
 
+/**
+ * Displays the aggregator administration page.
+ *
+ * @return
+ *   The page HTML.
+ */
 function aggregator_view() {
   $result = db_query('SELECT f.*, COUNT(i.iid) AS items FROM {aggregator_feed} f LEFT JOIN {aggregator_item} i ON f.fid = i.fid GROUP BY f.fid, f.title, f.url, f.refresh, f.checked, f.link, f.description, f.etag, f.modified, f.image, f.block ORDER BY f.title');
 
@@ -100,7 +106,6 @@ function aggregator_form_feed(&$form_state, $edit = array('refresh' => 900, 'tit
   return $form;
 }
 
-
 /**
  * Validate aggregator_form_feed form submissions.
  */
@@ -130,6 +135,7 @@ function aggregator_form_feed_validate($form, &$form_state) {
 
 /**
  * Process aggregator_form_feed form submissions.
+ *
  * @todo Add delete confirmation dialog.
  */
 function aggregator_form_feed_submit($form, &$form_state) {
@@ -172,6 +178,9 @@ function aggregator_form_feed_submit($form, &$form_state) {
 
 /**
  * Menu callback; removes all items from a feed, then redirects to the overview page.
+ *
+ * @param $feed
+ *   An associative array describing the feed to be cleared.
  */
 function aggregator_admin_remove_feed($feed) {
   aggregator_remove($feed);
@@ -180,6 +189,9 @@ function aggregator_admin_remove_feed($feed) {
 
 /**
  * Menu callback; refreshes a feed, then redirects to the overview page.
+ *
+ * @param $feed
+ *   An associative array describing the feed to be refreshed.
  */
 function aggregator_admin_refresh_feed($feed) {
   aggregator_refresh($feed);
@@ -271,6 +283,7 @@ function aggregator_form_category_validate($form, &$form_state) {
 
 /**
  * Process aggregator_form_category form submissions.
+ *
  * @todo Add delete confirmation dialog.
  */
 function aggregator_form_category_submit($form, &$form_state) {
diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module
index 560d4345b..9cd50b53f 100644
--- a/modules/aggregator/aggregator.module
+++ b/modules/aggregator/aggregator.module
@@ -246,20 +246,33 @@ function aggregator_menu() {
   return $items;
 }
 
+/**
+ * Menu callback.
+ *
+ * @return
+ *   An aggregator category title.
+ */
 function _aggregator_category_title($category) {
   return $category['title'];
 }
 
+/**
+ * Implementation of hook_init().
+ */
 function aggregator_init() {
   drupal_add_css(drupal_get_path('module', 'aggregator') .'/aggregator.css');
 }
 
+/**
+ * Find out whether there are any aggregator categories.
+ *
+ * @return
+ *   TRUE if there is at least one category and the user has access to them, FALSE otherwise.
+ */
 function _aggregator_has_categories() {
   return user_access('access news feeds') && db_result(db_query('SELECT COUNT(*) FROM {aggregator_category}'));
 }
 
-
-
 /**
  * Implementation of hook_perm().
  */
@@ -353,6 +366,9 @@ function aggregator_block($op = 'list', $delta = 0, $edit = array()) {
 
 /**
  * Add/edit/delete aggregator categories.
+ *
+ * @param $edit
+ *   An associative array describing the category to be added/edited/deleted.
  */
 function aggregator_save_category($edit) {
   $link_path = 'aggregator/categories/';
@@ -381,6 +397,9 @@ function aggregator_save_category($edit) {
 
 /**
  * Add/edit/delete an aggregator feed.
+ *
+ * @param $edit
+ *   An associative array describing the feed to be added/edited/deleted.
  */
 function aggregator_save_feed($edit) {
   if (!empty($edit['fid'])) {
@@ -419,6 +438,12 @@ function aggregator_save_feed($edit) {
   }
 }
 
+/**
+ * Removes all items from a feed.
+ *
+ * @param $feed
+ *   An associative array describing the feed to be cleared.
+ */
 function aggregator_remove($feed) {
   $result = db_query('SELECT iid FROM {aggregator_item} WHERE fid = %d', $feed['fid']);
   while ($item = db_fetch_object($result)) {
@@ -547,6 +572,9 @@ function aggregator_element_data($parser, $data) {
 
 /**
  * Checks a news feed for new items.
+ *
+ * @param $feed
+ *   An associative array describing the feed to be refreshed.
  */
 function aggregator_refresh($feed) {
   global $channel, $image;
@@ -634,8 +662,10 @@ function aggregator_refresh($feed) {
  * See http://www.w3.org/TR/NOTE-datetime for more information.
  * Originally from MagpieRSS (http://magpierss.sourceforge.net/).
  *
- * @param $date_str A string with a potentially W3C DTF date.
- * @return A timestamp if parsed successfully or -1 if not.
+ * @param $date_str
+ *   A string with a potentially W3C DTF date.
+ * @return
+ *   A timestamp if parsed successfully or FALSE if not.
  */
 function aggregator_parse_w3cdtf($date_str) {
   if (preg_match('/(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(:(\d{2}))?(?:([-+])(\d{2}):?(\d{2})|(Z))?/', $date_str, $match)) {
@@ -665,6 +695,16 @@ function aggregator_parse_w3cdtf($date_str) {
   }
 }
 
+/**
+ * Parse a feed and store its items.
+ *
+ * @param $data
+ *   The feed data.
+ * @param $feed
+ *   An associative array describing the feed to be parsed.
+ * @return
+ *   0 on error, 1 otherwise.
+ */
 function aggregator_parse_feed(&$data, $feed) {
   global $items, $image, $channel;
 
@@ -806,6 +846,12 @@ function aggregator_parse_feed(&$data, $feed) {
   return 1;
 }
 
+/**
+ * Add/edit/delete an aggregator item.
+ *
+ * @param $edit
+ *   An associative array describing the item to be added/edited/deleted.
+ */
 function aggregator_save_item($edit) {
   if ($edit['iid'] && $edit['title']) {
     db_query("UPDATE {aggregator_item} SET title = '%s', link = '%s', author = '%s', description = '%s', guid = '%s', timestamp = %d WHERE iid = %d", $edit['title'], $edit['link'], $edit['author'], $edit['description'], $edit['guid'], $edit['timestamp'], $edit['iid']);
@@ -825,6 +871,14 @@ function aggregator_save_item($edit) {
   }
 }
 
+/**
+ * Load an aggregator feed.
+ *
+ * @param $fid
+ *   The feed id.
+ * @return
+ *   An associative array describing the feed.
+ */
 function aggregator_feed_load($fid) {
   static $feeds;
   if (!isset($feeds[$fid])) {
@@ -833,6 +887,14 @@ function aggregator_feed_load($fid) {
   return $feeds[$fid];
 }
 
+/**
+ * Load an aggregator category.
+ *
+ * @param $cid
+ *   The category id.
+ * @return
+ *   An associative array describing the category.
+ */
 function aggregator_category_load($cid) {
   static $categories;
   if (!isset($categories[$cid])) {
@@ -844,6 +906,12 @@ function aggregator_category_load($cid) {
 /**
  * Format an individual feed item for display in the block.
  *
+ * @param $item
+ *   The item to be displayed.
+ * @param $feed
+ *   Not used.
+ * @return
+ *   The item HTML.
  * @ingroup themeable
  */
 function theme_aggregator_block_item($item, $feed = 0) {
@@ -864,6 +932,11 @@ function theme_aggregator_block_item($item, $feed = 0) {
 
 /**
  * Safely render HTML content, as allowed.
+ *
+ * @param $value
+ *   The content to be filtered.
+ * @return
+ *   The filtered content.
  */
 function aggregator_filter_xss($value) {
   return filter_xss($value, preg_split('/\s+|<|>/', variable_get('aggregator_allowed_html_tags', '<a> <b> <br> <dd> <dl> <dt> <em> <i> <li> <ol> <p> <strong> <u> <ul>'), -1, PREG_SPLIT_NO_EMPTY));
@@ -871,6 +944,11 @@ function aggregator_filter_xss($value) {
 
 /**
  * Helper function for drupal_map_assoc.
+ *
+ * @param $count
+ *   Items count.
+ * @return
+ *   Plural-formatted "@count items"
  */
 function _aggregator_items($count) {
   return format_plural($count, '1 item', '@count items');
diff --git a/modules/aggregator/aggregator.pages.inc b/modules/aggregator/aggregator.pages.inc
index 0575103e9..2c33ad6d5 100644
--- a/modules/aggregator/aggregator.pages.inc
+++ b/modules/aggregator/aggregator.pages.inc
@@ -8,6 +8,9 @@
 
 /**
  * Menu callback; displays the most recent items gathered from any feed.
+ *
+ * @return
+ *   The items HTML.
  */
 function aggregator_page_last() {
   drupal_add_feed(url('aggregator/rss'), variable_get('site_name', 'Drupal') .' '. t('aggregator'));
@@ -19,6 +22,15 @@ function aggregator_page_last() {
 
 /**
  * Menu callback; displays all the items captured from a particular feed.
+ *
+ * If there are two arguments then this function is the categorize form.
+ *
+ * @param $arg1
+ *   If there are two arguments then $arg1 is $form_state. Otherwise, $arg1 is $feed.
+ * @param $arg2
+ *   If there are two arguments then $arg2 is feed.
+ * @return
+ *   The items HTML.
  */
 function aggregator_page_source($arg1, $arg2 = NULL) {
   // If there are two arguments then this function is the categorize form, and
@@ -37,6 +49,15 @@ function aggregator_page_source($arg1, $arg2 = NULL) {
 
 /**
  * Menu callback; displays all the items aggregated in a particular category.
+ *
+ * If there are two arguments then this function is called as a form.
+ *
+ * @param $arg1
+ *   If there are two arguments then $arg1 is $form_state. Otherwise, $arg1 is $category.
+ * @param $arg2
+ *   If there are two arguments then $arg2 is $category.
+ * @return
+ *   The items HTML.
  */
 function aggregator_page_category($arg1, $arg2 = NULL) {
   drupal_set_breadcrumb(array_merge(drupal_get_breadcrumb(), array(l(t('Categories'), 'aggregator/categories'))));
@@ -54,7 +75,12 @@ function aggregator_page_category($arg1, $arg2 = NULL) {
 }
 
 /**
- * Load feed items by passing a sql query.
+ * Load feed items by passing a SQL query.
+ *
+ * @param $sql
+ *   The query to be executed.
+ * @return
+ *   An array of the feed items.
  */
 function aggregator_feed_items_load($sql) {
   $items = array();
@@ -73,8 +99,18 @@ function aggregator_feed_items_load($sql) {
 }
 
 /**
- * Prints an aggregator page listing a number of feed items. Various
- * menu callbacks use this function to print their feeds.
+ * Prints an aggregator page listing a number of feed items.
+ *
+ * Various menu callbacks use this function to print their feeds.
+ *
+ * @param $items
+ *   The items to be listed.
+ * @param $op
+ *   Which form should be added to the items. Only 'categorize' is now recognized.
+ * @param $feed_source
+ *   The feed source URL.
+ * @return
+ *   The items HTML.
  */
 function _aggregator_page_list($items, $op, $feed_source = '') {
   if (user_access('administer news feeds') && ($op == 'categorize')) {
@@ -95,6 +131,12 @@ function _aggregator_page_list($items, $op, $feed_source = '') {
 /**
  * Form builder; build the page list form.
  *
+ * @param $items
+ *   An array of the feed items.
+ * @param $feed_source
+ *   The feed source URL.
+ * @return
+ *   The form structure.
  * @ingroup forms
  * @see aggregator_categorize_items_validate().
  * @see aggregator_categorize_items_submit().
@@ -135,12 +177,18 @@ function aggregator_categorize_items($items, $feed_source = '') {
   return $form;
 }
 
+/**
+ * Validate aggregator_categorize_items form submissions.
+ */
 function aggregator_categorize_items_validate($form_id, &$form) {
   if (!user_access('administer news feeds')) {
     form_error($form, t('You are not allowed to categorize this feed item.'));
   }
 }
 
+/**
+ * Process aggregator_categorize_items form submissions.
+ */
 function aggregator_categorize_items_submit($form, &$form_state) {
   foreach ($form_state['values']['categories'] as $iid => $selection) {
     db_query('DELETE FROM {aggregator_category_item} WHERE iid = %d', $iid);
@@ -156,6 +204,10 @@ function aggregator_categorize_items_submit($form, &$form_state) {
 /**
  * Theme the page list form for assigning categories.
  *
+ * @param $form
+ *   An associative array containing the structure of the form.
+ * @return
+ *   The output HTML.
  * @ingroup themeable
  */
 function theme_aggregator_categorize_items($form) {
@@ -180,9 +232,6 @@ function theme_aggregator_categorize_items($form) {
 /**
  * Process variables for aggregator-wrapper.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $content
- *
  * @see aggregator-wrapper.tpl.php
  */
 function template_preprocess_aggregator_wrapper(&$variables) {
@@ -192,9 +241,6 @@ function template_preprocess_aggregator_wrapper(&$variables) {
 /**
  * Process variables for aggregator-item.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $item
- *
  * @see aggregator-item.tpl.php
  */
 function template_preprocess_aggregator_item(&$variables) {
@@ -294,8 +340,12 @@ function aggregator_page_rss() {
 }
 
 /**
- * Theme the rss output.
+ * Theme the RSS output.
  *
+ * @param $feeds
+ *   An array of the feeds to theme.
+ * @param $category
+ *   A common category, if any, for all the feeds.
  * @ingroup themeable
  */
 function theme_aggregator_page_rss($feeds, $category = NULL) {
@@ -333,6 +383,11 @@ function theme_aggregator_page_rss($feeds, $category = NULL) {
 
 /**
  * Menu callback; generates an OPML representation of all feeds.
+ *
+ * @param $cid
+ *   If set, feeds are exported only from a category with this ID. Otherwise, all feeds are exported.
+ * @return
+ *   The output XML.
  */
 function aggregator_page_opml($cid = NULL) {
   if ($cid) {
@@ -350,8 +405,10 @@ function aggregator_page_opml($cid = NULL) {
 }
 
 /**
- * Theme the opml feed output.
+ * Theme the OPML feed output.
  *
+ * @param $feeds
+ *   An array of the feeds to theme.
  * @ingroup themeable
  */
 function theme_aggregator_page_opml($feeds) {
@@ -378,10 +435,6 @@ function theme_aggregator_page_opml($feeds) {
 /**
  * Process variables for aggregator-summary-items.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $summary_items
- * - $source
- *
  * @see aggregator-summary-item.tpl.php
  */
 function template_preprocess_aggregator_summary_items(&$variables) {
@@ -393,9 +446,6 @@ function template_preprocess_aggregator_summary_items(&$variables) {
 /**
  * Process variables for aggregator-summary-item.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $item
- *
  * @see aggregator-summary-item.tpl.php
  */
 function template_preprocess_aggregator_summary_item(&$variables) {
@@ -416,9 +466,6 @@ function template_preprocess_aggregator_summary_item(&$variables) {
 /**
  * Process variables for aggregator-feed-source.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $feed
- *
  * @see aggregator-feed-source.tpl.php
  */
 function template_preprocess_aggregator_feed_source(&$variables) {
diff --git a/modules/comment/comment.admin.inc b/modules/comment/comment.admin.inc
index 9150a1d52..648a90912 100644
--- a/modules/comment/comment.admin.inc
+++ b/modules/comment/comment.admin.inc
@@ -23,6 +23,12 @@ function comment_admin($type = 'new') {
 /**
  * Form builder; Builds the comment overview form for the admin.
  *
+ * @param $type
+ *   Not used.
+ * @param $arg
+ *   Current path's fourth component deciding the form type (Published comments/Approval queue)
+ * @return
+ *   The form structure.
  * @ingroup forms
  * @see comment_admin_overview_validate().
  * @see comment_admin_overview_submit().
@@ -70,6 +76,8 @@ function comment_admin_overview($type = 'new', $arg) {
 }
 
 /**
+ * Validate comment_admin_overview form submissions.
+ *
  * We can't execute any 'Update options' if no comments were selected.
  */
 function comment_admin_overview_validate($form, &$form_state) {
@@ -81,6 +89,8 @@ function comment_admin_overview_validate($form, &$form_state) {
 }
 
 /**
+ * Process comment_admin_overview form submissions.
+ *
  * Execute the chosen 'Update option' on the selected comments, such as
  * publishing, unpublishing or deleting.
  */
@@ -110,6 +120,8 @@ function comment_admin_overview_submit($form, &$form_state) {
 /**
  * Theme the comment admin form.
  *
+ * @param $form
+ *   An associative array containing the structure of the form.
  * @ingroup themeable
  */
 function theme_comment_admin_overview($form) {
@@ -144,6 +156,10 @@ function theme_comment_admin_overview($form) {
  * List the selected comments and verify that the admin really wants to delete
  * them.
  *
+ * @param $form_state
+ *   An associative array containing the current state of the form.
+ * @return
+ *   TRUE if the comments should be deleted, FALSE otherwise.
  * @ingroup forms
  * @see comment_multiple_delete_confirm_submit().
  */
@@ -176,6 +192,8 @@ function comment_multiple_delete_confirm(&$form_state) {
 }
 
 /**
+ * Process comment_multiple_delete_confirm form submissions.
+ *
  * Perform the actual comment deletion.
  */
 function comment_multiple_delete_confirm_submit($form, &$form_state) {
@@ -193,6 +211,9 @@ function comment_multiple_delete_confirm_submit($form, &$form_state) {
 
 /**
  * Menu callback; delete a comment.
+ *
+ * @param $cid
+ *   The comment do be deleted.
  */
 function comment_delete($cid = NULL) {
   $comment = db_fetch_object(db_query('SELECT c.*, u.name AS registered_name, u.uid FROM {comments} c INNER JOIN {users} u ON u.uid = c.uid WHERE c.cid = %d', $cid));
@@ -229,6 +250,9 @@ function comment_confirm_delete(&$form_state, $comment) {
     'comment_confirm_delete');
 }
 
+/**
+ * Process comment_confirm_delete form submissions.
+ */
 function comment_confirm_delete_submit($form, &$form_state) {
   drupal_set_message(t('The comment and all its replies have been deleted.'));
 
@@ -246,6 +270,12 @@ function comment_confirm_delete_submit($form, &$form_state) {
   return;
 }
 
+/**
+ * Perform the actual deletion of a comment and all its replies.
+ *
+ * @param $comment
+ *   An associative array describing the comment to be deleted.
+ */
 function _comment_delete_thread($comment) {
   if (!is_object($comment) || !is_numeric($comment->cid)) {
     watchdog('content', 'Cannot delete non-existent comment.', WATCHDOG_WARNING);
diff --git a/modules/comment/comment.install b/modules/comment/comment.install
index 4cbc31fe5..5f919bcc5 100644
--- a/modules/comment/comment.install
+++ b/modules/comment/comment.install
@@ -10,8 +10,7 @@ function comment_enable() {
 }
 
 /**
- * Changed node_comment_statistics to use node->changed to avoid future
- * timestamps.
+ * Changed node_comment_statistics to use node->changed to avoid future timestamps.
  */
 function comment_update_1() {
   // Change any future last comment timestamps to now.
diff --git a/modules/comment/comment.module b/modules/comment/comment.module
index 98dc553f4..76da6216d 100644
--- a/modules/comment/comment.module
+++ b/modules/comment/comment.module
@@ -138,7 +138,7 @@ function comment_help($path, $arg) {
 }
 
 /**
- * Implementation of hook_theme()
+ * Implementation of hook_theme().
  */
 function comment_theme() {
   return array(
@@ -245,7 +245,6 @@ function comment_menu() {
 
 /**
  * Implementation of hook_node_type().
- *
  */
 function comment_node_type($op, $info) {
   $settings = array(
@@ -300,8 +299,10 @@ function comment_block($op = 'list', $delta = 0) {
  *   2. Loading the information from the comments table based on the nids found
  *      in step 1.
  *
- * @param $number (optional) The maximum number of comments to find.
- * @return $comments An array of comment objects each containing a nid,
+ * @param $number
+ *   (optional) The maximum number of comments to find.
+ * @return
+ *   An array of comment objects each containing a nid,
  *   subject, cid, and timestamp, or an empty array if there are no recent
  *   comments visible to the current user.
  */
@@ -331,6 +332,15 @@ function comment_get_recent($number = 10) {
 
 /**
  * Calculate page number for first new comment.
+ *
+ * @param $num_comments
+ *   Number of comments.
+ * @param $new_replies
+ *   Number of new replies.
+ * @param $node
+ *   The first new comment node.
+ * @return
+ *   "page=X" if the page number is greater than zero; empty string otherwise.
  */
 function comment_new_page_count($num_comments, $new_replies, $node) {
   $comments_per_page = _comment_get_display_setting('comments_per_page', $node);
@@ -373,9 +383,10 @@ function comment_new_page_count($num_comments, $new_replies, $node) {
 }
 
 /**
- * Returns a formatted list of recent comments to be displayed in the comment
- * block.
+ * Returns a formatted list of recent comments to be displayed in the comment block.
  *
+ * @return
+ *   The comment list HTML.
  * @ingroup themeable
  */
 function theme_comment_block() {
@@ -471,6 +482,9 @@ function comment_link($type, $node = NULL, $teaser = FALSE) {
   return $links;
 }
 
+/**
+ * Implementation of hook_form_alter().
+ */
 function comment_form_alter(&$form, $form_state, $form_id) {
   if ($form_id == 'node_type_form' && isset($form['identity']['type'])) {
     $form['comment'] = array(
@@ -575,7 +589,6 @@ function comment_form_alter(&$form, $form_state, $form_id) {
 
 /**
  * Implementation of hook_nodeapi().
- *
  */
 function comment_nodeapi(&$node, $op, $arg = 0) {
   switch ($op) {
@@ -637,6 +650,13 @@ function comment_user($type, $edit, &$user, $category = NULL) {
  * Authenticated users can edit their comments as long they have not been
  * replied to. This prevents people from changing or revising their
  * statements based on the replies to their posts.
+ *
+ * @param $op
+ *   The operation that is to be performed on the comment. Only 'edit' is recognized now.
+ * @param $comment
+ *   The comment object.
+ * @return
+ *   TRUE if the current user has acces to the comment, FALSE otherwise.
  */
 function comment_access($op, $comment) {
   global $user;
@@ -646,6 +666,12 @@ function comment_access($op, $comment) {
   }
 }
 
+/**
+ * A simple helper function.
+ *
+ * @return
+ *   The 0th and the 1st path components joined by a slash.
+ */
 function comment_node_url() {
   return arg(0) .'/'. arg(1);
 }
@@ -767,6 +793,16 @@ function comment_save($edit) {
   }
 }
 
+/**
+ * Build command links for a comment (e.g.\ edit, reply, delete) with respect to the current user's access permissions.
+ *
+ * @param $comment
+ *   The comment to which the links will be related.
+ * @param $return
+ *   Not used.
+ * @return
+ *   An associative array containing the links.
+ */
 function comment_links($comment, $return = 1) {
   global $user;
 
@@ -1025,6 +1061,11 @@ function comment_render($node, $cid = 0) {
 /**
  * Comment operations. We offer different update operations depending on
  * which comment administration page we're on.
+ *
+ * @param $action
+ *   The comment administration page.
+ * @return
+ *   An associative array containing the offered operations.
  */
 function comment_operations($action = NULL) {
   if ($action == 'publish') {
@@ -1055,11 +1096,24 @@ function comment_operations($action = NULL) {
 
 /**
  * Load the entire comment by cid.
+ *
+ * @param $cid
+ *   The identifying comment id.
+ * @return
+ *   The comment object.
  */
 function _comment_load($cid) {
   return db_fetch_object(db_query('SELECT * FROM {comments} WHERE cid = %d', $cid));
 }
 
+/**
+ * Get comment count for a node.
+ *
+ * @param $nid
+ *   The node id.
+ * @return
+ *   The comment count.
+ */
 function comment_num_all($nid) {
   static $cache;
 
@@ -1069,6 +1123,14 @@ function comment_num_all($nid) {
   return $cache[$nid];
 }
 
+/**
+ * Get replies count for a comment.
+ *
+ * @param $pid
+ *   The comment id.
+ * @return
+ *   The replies count.
+ */
 function comment_num_replies($pid) {
   static $cache;
 
@@ -1080,10 +1142,12 @@ function comment_num_replies($pid) {
 }
 
 /**
- * get number of new comments for current user and specified node
+ * Get number of new comments for current user and specified node.
  *
- * @param $nid node-id to count comments for
- * @param $timestamp time to count from (defaults to time of last user access
+ * @param $nid
+ *   node-id to count comments for
+ * @param $timestamp
+ *   time to count from (defaults to time of last user access
  *   to node)
  */
 function comment_num_new($nid, $timestamp = 0) {
@@ -1108,6 +1172,14 @@ function comment_num_new($nid, $timestamp = 0) {
 
 }
 
+/**
+ * Validate comment data.
+ *
+ * @param $edit
+ *   An associative array containig the comment data.
+ * @return
+ *   The original $edit.
+ */
 function comment_validate($edit) {
   global $user;
 
@@ -1163,10 +1235,11 @@ function comment_validate($edit) {
 /**
  * Generate the basic commenting form, for appending to a node or display on a separate page.
  *
+ * @param $title
+ *   Not used.
  * @ingroup forms
  * @see comment_form_validate().
  * @see comment_form_submit().
- *
  */
 function comment_form(&$form_state, $edit, $title = NULL) {
   global $user;
@@ -1333,10 +1406,23 @@ function comment_form(&$form_state, $edit, $title = NULL) {
   return $form;
 }
 
+/**
+ * Theme the comment form box.
+ *
+ * @param $edit
+ *   The form structure.
+ * @param $title
+ *   The form title.
+ */
 function comment_form_box($edit, $title = NULL) {
   return theme('box', $title, drupal_get_form('comment_form', $edit, $title));
 }
 
+/**
+ * Form builder; Generate and validate a comment preview form.
+ *
+ * @ingroup forms
+ */
 function comment_form_add_preview($form, &$form_state) {
   global $user;
   $edit = $form_state['values'];
@@ -1397,6 +1483,9 @@ function comment_form_add_preview($form, &$form_state) {
   return $form;
 }
 
+/**
+ * Validate comment form submissions.
+ */
 function comment_form_validate($form, &$form_state) {
   global $user;
   if ($user->uid === 0) {
@@ -1410,6 +1499,12 @@ function comment_form_validate($form, &$form_state) {
   comment_validate($form_state['values']);
 }
 
+/**
+ * Prepare a comment for submission.
+ *
+ * @param $comment_values
+ *   An associative array containing the comment data.
+ */
 function _comment_form_submit(&$comment_values) {
   $comment_values += array('subject' => '');
   if (!isset($comment_values['date'])) {
@@ -1438,6 +1533,9 @@ function _comment_form_submit(&$comment_values) {
   }
 }
 
+/**
+ * Process comment form submissions; prepare the comment, store it, and set a redirection target.
+ */
 function comment_form_submit($form, &$form_state) {
   _comment_form_submit($form_state['values']);
   if ($cid = comment_save($form_state['values'])) {
@@ -1449,11 +1547,19 @@ function comment_form_submit($form, &$form_state) {
 }
 
 /**
- * Return a themed comment.
+ * Theme a single comment block.
  *
+ * @param $comment
+ *   The comment object.
+ * @param $node
+ *   The comment node.
+ * @param $links
+ *   An associative array containing control links.
+ * @param $visible
+ *   Switches between folded/unfolded view.
  * @ingroup themeable
  */
-function theme_comment_view($comment, $node, $links = array(), $visible = 1) {
+function theme_comment_view($comment, $node, $links = array(), $visible = TRUE) {
   static $first_new = TRUE;
 
   $output = '';
@@ -1483,6 +1589,18 @@ function theme_comment_view($comment, $node, $links = array(), $visible = 1) {
   return $output;
 }
 
+
+/**
+ * Build a comment control form.
+ *
+ * @param $mode
+ *   Comment display mode.
+ * @param $order
+ *   Comment order mode.
+ * @param $comments_per_page
+ *   Comments per page.
+ * @ingroup forms
+ */
 function comment_controls($mode = COMMENT_MODE_THREADED_EXPANDED, $order = COMMENT_ORDER_NEWEST_FIRST, $comments_per_page = 50) {
   $form['mode'] = array('#type' => 'select',
     '#default_value' => $mode,
@@ -1511,9 +1629,12 @@ function comment_controls($mode = COMMENT_MODE_THREADED_EXPANDED, $order = COMME
 
   return $form;
 }
+
 /**
  * Theme comment controls box where the user can change the default display mode and display order of comments.
  *
+ * @param $form
+ *   The form structure.
  * @ingroup themeable
  */
 function theme_comment_controls($form) {
@@ -1524,6 +1645,9 @@ function theme_comment_controls($form) {
   return theme('box', t('Comment viewing options'), $output);
 }
 
+/**
+ * Process comment_controls form submissions.
+ */
 function comment_controls_submit($form, &$form_state) {
   global $user;
 
@@ -1544,11 +1668,6 @@ function comment_controls_submit($form, &$form_state) {
 /**
  * Process variables for comment.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $comment
- * - $node
- * - $links
- *
  * @see comment.tpl.php
  * @see theme_comment()
  */
@@ -1570,9 +1689,6 @@ function template_preprocess_comment(&$variables) {
 /**
  * Process variables for comment-folded.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $comment
- *
  * @see comment-folded.tpl.php
  * @see theme_comment_folded()
  */
@@ -1585,8 +1701,12 @@ function template_preprocess_comment_folded(&$variables) {
 }
 
 /**
- * Theme collapsed flat type comment.
+ * Theme comment flat collapsed view.
  *
+ * @param $comment
+ *   The comment to be themed.
+ * @param $node
+ *   The comment node.
  * @ingroup themeable
  */
 function theme_comment_flat_collapsed($comment, $node) {
@@ -1594,8 +1714,12 @@ function theme_comment_flat_collapsed($comment, $node) {
 }
 
 /**
- * Theme expanded flat type comment.
+ * Theme comment flat expanded view.
  *
+ * @param $comment
+ *   The comment to be themed.
+ * @param $node
+ *   The comment node.
  * @ingroup themeable
  */
 function theme_comment_flat_expanded($comment, $node) {
@@ -1603,8 +1727,12 @@ function theme_comment_flat_expanded($comment, $node) {
 }
 
 /**
- * Theme collapsed thread type comment.
+ * Theme comment thread collapsed view.
  *
+ * @param $comment
+ *   The comment to be themed.
+ * @param $node
+ *   The comment node.
  * @ingroup themeable
  */
 function theme_comment_thread_collapsed($comment, $node) {
@@ -1612,8 +1740,12 @@ function theme_comment_thread_collapsed($comment, $node) {
 }
 
 /**
- * Theme expanded thread type comment.
+ * Theme comment thread expanded view.
  *
+ * @param $comment
+ *   The comment to be themed.
+ * @param $node
+ *   The comment node.
  * @ingroup themeable
  */
 function theme_comment_thread_expanded($comment, $node) {
@@ -1621,8 +1753,10 @@ function theme_comment_thread_expanded($comment, $node) {
 }
 
 /**
- * Theme the "comment posting is forbidden" message.
+ * Theme a "you can't post comments" notice.
  *
+ * @param $node
+ *   The comment node.
  * @ingroup themeable
  */
 function theme_comment_post_forbidden($node) {
@@ -1651,10 +1785,6 @@ function theme_comment_post_forbidden($node) {
 /**
  * Process variables for comment-wrapper.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $content
- * - $node
- *
  * @see comment-wrapper.tpl.php
  * @see theme_comment_wrapper()
  */
@@ -1667,8 +1797,10 @@ function template_preprocess_comment_wrapper(&$variables) {
 }
 
 /**
- * Make the submitted variable themable
+ * Theme a "Submitted by ..." notice.
  *
+ * @param $comment
+ *   The comment.
  * @ingroup themeable
  */
 function theme_comment_submitted($comment) {
@@ -1718,7 +1850,10 @@ function _comment_per_page() {
 /**
  * Return a current comment display setting
  *
- * $setting can be one of these: 'mode', 'sort', 'comments_per_page'
+ * @param $setting
+ *   can be one of these: 'mode', 'sort', 'comments_per_page'
+ * @param $node
+ *   The comment node in question.
  */
 function _comment_get_display_setting($setting, $node) {
   global $user;
@@ -1809,7 +1944,6 @@ function comment_invoke_comment(&$comment, $op) {
   return $return;
 }
 
-
 /**
  * Generate vancode.
  *
@@ -1905,6 +2039,11 @@ function comment_unpublish_action($comment, $context = array()) {
   watchdog('action', 'Unpublished comment %subject.', array('%subject' => $subject));
 }
 
+/**
+ * Form builder; Prepare a form for blacklisted keywords.
+ *
+ * @ingroup forms
+ */
 function comment_unpublish_by_keyword_action_form($context) {
   $form['keywords'] = array(
     '#title' => t('Keywords'),
@@ -1915,6 +2054,9 @@ function comment_unpublish_by_keyword_action_form($context) {
   return $form;
 }
 
+/**
+ * Process comment_unpublish_by_keyword_action_form form submissions.
+ */
 function comment_unpublish_by_keyword_action_submit($form, $form_state) {
   return array('keywords' => drupal_explode_tags($form_state['values']['keywords']));
 }
diff --git a/modules/comment/comment.pages.inc b/modules/comment/comment.pages.inc
index 7e979a1fb..f4b770677 100644
--- a/modules/comment/comment.pages.inc
+++ b/modules/comment/comment.pages.inc
@@ -6,6 +6,13 @@
  * User page callbacks for the comment module.
  */
 
+/**
+ * Form builder; generate a comment editing form.
+ *
+ * @param $cid
+ *   ID of the comment to be edited.
+ * @ingroup forms
+ */
 function comment_edit($cid) {
   global $user;
 
@@ -33,11 +40,12 @@ function comment_edit($cid) {
  *
  * @param $node
  *   Every comment belongs to a node. This is that node.
+ *
  * @param $pid
  *   Some comments are replies to other comments. In those cases, $pid is the parent
  *   comment's cid.
  *
- * @return $output
+ * @return
  *   The rendered parent node or comment plus the new comment form.
  */
 function comment_reply($node, $pid = NULL) {
diff --git a/modules/system/box.tpl.php b/modules/system/box.tpl.php
index 338bf8c63..796c3dcfe 100644
--- a/modules/system/box.tpl.php
+++ b/modules/system/box.tpl.php
@@ -1,5 +1,17 @@
 <?php
 // $Id$
+
+/**
+ * @file box.tpl.php
+ *
+ * Theme implementation to display a box.
+ *
+ * Available variables:
+ * - $title: Box title.
+ * - $content: Box content.
+ *
+ * @see template_preprocess()
+ */
 ?>
 <div class="box">
 
diff --git a/modules/system/system.admin.inc b/modules/system/system.admin.inc
index a81f36f3d..02c0076a1 100644
--- a/modules/system/system.admin.inc
+++ b/modules/system/system.admin.inc
@@ -66,6 +66,9 @@ function system_main_admin_page($arg = NULL) {
  * For example, 'admin/content/types' needs to have a destination to be valid
  * in the Drupal menu system, but too much information there might be
  * hidden, so we supply the contents of the block.
+ *
+ * @return
+ *   The output HTML.
  */
 function system_admin_menu_block_page() {
   $item = menu_get_item();
@@ -77,6 +80,9 @@ function system_admin_menu_block_page() {
 
 /**
  * Menu callback; Sets whether the admin menu is in compact mode or not.
+ *
+ * @param $mode
+ *   Valid values are 'on' and 'off'.
  */
 function system_admin_compact_page($mode = 'off') {
   global $user;
@@ -241,6 +247,9 @@ function system_themes_form() {
   return $form;
 }
 
+/**
+ * Process system_themes_form form submissions.
+ */
 function system_themes_form_submit($form, &$form_state) {
 
   // Store list of previously enabled themes and disable all themes
@@ -296,6 +305,10 @@ function system_themes_form_submit($form, &$form_state) {
 /**
  * Form builder; display theme configuration for entire site and individual themes.
  *
+ * @param $key
+ *   A theme name.
+ * @return
+ *   The form structure.
  * @ingroup forms
  * @see system_theme_settings_submit().
  */
@@ -512,6 +525,9 @@ function system_theme_settings(&$form_state, $key = '') {
   return $form;
 }
 
+/**
+ * Process system_theme_settings form submissions.
+ */
 function system_theme_settings_submit($form, &$form_state) {
   $op = isset($_POST['op']) ? $_POST['op'] : '';
   $key = $form_state['values']['var'];
@@ -532,7 +548,16 @@ function system_theme_settings_submit($form, &$form_state) {
 }
 
 /**
- * Recursively check compatability
+ * Recursively check compatibility.
+ *
+ * @param $incompatible
+ *   An associative array which at the end of the check contains all incompatible files as the keys, their values being TRUE.
+ * @param $files
+ *   The set of files that will be tested.
+ * @param $file
+ *   The file at which the check starts.
+ * @return
+ *   Returns TRUE if an incompatible file is found, NULL (no return value) otherwise.
  */
 function _system_is_incompatible(&$incompatible, $files, $file) {
   static $seen;
@@ -565,6 +590,8 @@ function _system_is_incompatible(&$incompatible, $files, $file) {
  * disabled dependencies and also to ensure that the module cannot be disabled if the module has
  * enabled dependents.
  *
+ * @param $form_state
+ *   An associative array containing the current state of the form.
  * @ingroup forms
  * @see theme_system_modules().
  * @see system_modules_submit().
@@ -726,12 +753,23 @@ function system_modules($form_state = array()) {
   return $form;
 }
 
+/**
+ * Array sorting callback; sorts modules by their name.
+ */
 function system_sort_modules_by_info_name($a, $b) {
   return strcasecmp($a->info['name'], $b->info['name']);
 }
 
 /**
  * Form process callback function to disable check boxes.
+ *
+ * @param $form
+ *   The form structure.
+ * @param $edit
+ *   Not used.
+ * @ingroup forms
+ * @return
+ *   The form structure.
  */
 function system_modules_disable($form, $edit) {
   foreach ($form['#disabled_modules'] as $key) {
@@ -750,7 +788,6 @@ function system_modules_disable($form, $edit) {
  *   elements: the list of dependencies and the list of status
  *   form field values from the previous screen.
  * @ingroup forms
- * @see
  */
 function system_modules_confirm_form($modules, $storage) {
   $form = array();
@@ -893,6 +930,17 @@ function system_modules_submit($form, &$form_state) {
   return;
 }
 
+
+/**
+ * Generate a list of dependencies for modules that are going to be switched on.
+ *
+ * @param $modules
+ *   The list of modules to check.
+ * @param $form_values
+ *   Submitted form values used to determine what modules have been enabled.
+ * @return
+ *   An array of dependencies.
+ */
 function system_module_build_dependencies($modules, $form_values) {
   static $dependencies;
 
@@ -925,8 +973,8 @@ function system_module_build_dependencies($modules, $form_values) {
  * @ingroup forms
  * @see system_modules_uninstall_validate().
  * @see system_modules_uninstall_submit().
- * @param
- *   $form_state['values'] Submitted form values.
+ * @param $form_state['values']
+ *   Submitted form values.
  * @return
  *   A form array representing the currently disabled modules.
  */
@@ -981,8 +1029,8 @@ function system_modules_uninstall($form_state = NULL) {
  * Confirm uninstall of selected modules.
  *
  * @ingroup forms
- * @param
- *   $form_state['values'] Submitted form values.
+ * @param $storage
+ *   An associative array of modules selected to be uninstalled.
  * @return
  *   A form array representing modules to confirm.
  */
@@ -1019,11 +1067,6 @@ function system_modules_uninstall_confirm_form($storage) {
 
 /**
  * Validates the submitted uninstall form.
- *
- * @param
- *   $form_id The form ID.
- * @param
- *   $form_state['values'] Submitted form values.
  */
 function system_modules_uninstall_validate($form, &$form_state) {
   // Form submitted, but no modules selected.
@@ -1035,11 +1078,6 @@ function system_modules_uninstall_validate($form, &$form_state) {
 
 /**
  * Processes the submitted uninstall form.
- *
- * @param
- *   $form_id The form ID.
- * @param
- *   $form_state['values'] Submitted form values.
  */
 function system_modules_uninstall_submit($form, &$form_state) {
   // Make sure the install API is available.
@@ -1274,7 +1312,9 @@ function system_performance_settings() {
 }
 
 /**
- * Clear system caches.
+ * Submit callback; clear system caches.
+ *
+ * @ingroup forms
  */
 function system_clear_cache_submit(&$form_state, $form) {
   drupal_flush_all_caches();
@@ -1374,7 +1414,7 @@ function system_rss_feeds_settings() {
  *
  * @ingroup forms
  * @see system_settings_form().
- * @see system_date_time_settings().
+ * @see system_date_time_settings_submit().
  */
 function system_date_time_settings() {
   drupal_add_js(drupal_get_path('module', 'system') .'/system.js', 'module');
@@ -1517,6 +1557,9 @@ function system_date_time_settings() {
   return $form;
 }
 
+/**
+ * Process system_date_time_settings form submissions.
+ */
 function system_date_time_settings_submit($form, &$form_state) {
   if ($form_state['values']['date_format_short'] == 'custom') {
     $form_state['values']['date_format_short'] = $form_state['values']['date_format_short_custom'];
@@ -1602,6 +1645,7 @@ function system_clean_url_settings() {
  * Menu callback: displays the site status report. Can also be used as a pure check.
  *
  * @param $check
+ *
  *   If true, only returns a boolean whether there are system status errors.
  */
 function system_status($check = FALSE) {
@@ -1643,6 +1687,16 @@ function system_php() {
   exit();
 }
 
+/**
+ * Theme a SQL result table.
+ *
+ * @param $data
+ *   The actual table data.
+ * @param $keys
+ *   Data keys and descriptions.
+ * @return
+ *   The output HTML.
+ */
 function _system_sql($data, $keys) {
   $rows = array();
   foreach ($keys as $key => $explanation) {
@@ -1717,7 +1771,6 @@ function system_batch_page() {
  * @param $block
  *   An array containing information about the block. It should
  *   include a 'title', a 'description' and a formatted 'content'.
- *
  * @ingroup themeable
  */
 function theme_admin_block($block) {
@@ -1748,7 +1801,6 @@ EOT;
  * @param $block
  *   An array containing information about the block. It should
  *   include a 'title', a 'description' and a formatted 'content'.
- *
  * @ingroup themeable
  */
 function theme_admin_block_content($content) {
@@ -1786,7 +1838,6 @@ function theme_admin_block_content($content) {
  *   'title', a 'description', a formatted 'content' and a
  *   'position' which will control which container it will be
  *   in. This is usually 'left' or 'right'.
- *
  * @ingroup themeable
  */
 function theme_admin_page($blocks) {
@@ -1828,6 +1879,8 @@ function theme_admin_page($blocks) {
 /**
  * Theme output of the dashboard page.
  *
+ * @param $menu_items
+ *   An array of modules to be displayed.
  * @ingroup themeable
  */
 function theme_system_admin_by_module($menu_items) {
@@ -1871,8 +1924,10 @@ function theme_system_admin_by_module($menu_items) {
 }
 
 /**
- * Theme status report
+ * Theme requirements status report.
  *
+ * @param $requirements
+ *   An array of requirements.
  * @ingroup themeable
  */
 function theme_status_report(&$requirements) {
@@ -1906,8 +1961,10 @@ function theme_status_report(&$requirements) {
 }
 
 /**
- * Theme call back for the modules form.
+ * Theme callback for the modules form.
  *
+ * @param $form
+ *   An associative array containing the structure of the form.
  * @ingroup themeable
  */
 function theme_system_modules($form) {
@@ -1993,8 +2050,8 @@ function theme_system_modules($form) {
  * Themes a table of currently disabled modules.
  *
  * @ingroup themeable
- * @param
- *   $form The form array representing the currently disabled modules.
+ * @param $form
+ *   The form array representing the currently disabled modules.
  * @return
  *   An HTML string representing the table.
  */
@@ -2033,7 +2090,8 @@ function theme_system_modules_uninstall($form) {
 
 /**
  * Theme the theme select form.
- *
+ * @param $form
+ *   An associative array containing the structure of the form.
  * @ingroup themeable
  */
 function theme_system_theme_select_form($form) {
@@ -2055,6 +2113,8 @@ function theme_system_theme_select_form($form) {
 /**
  * Theme function for the system themes form.
  *
+ * @param $form
+ *   An associative array containing the structure of the form.
  * @ingroup themeable
  */
 function theme_system_themes_form($form) {
diff --git a/modules/system/system.install b/modules/system/system.install
index 122bd2e71..510283dfc 100644
--- a/modules/system/system.install
+++ b/modules/system/system.install
@@ -3,6 +3,11 @@
 
 /**
  * Test and report Drupal installation requirements.
+ *
+ * @param $phase
+ *   The current system installation phase.
+ * @return
+ *   An array of system requirements.
  */
 function system_requirements($phase) {
   $requirements = array();
@@ -243,7 +248,6 @@ function system_requirements($phase) {
   return $requirements;
 }
 
-
 /**
  * Implementation of hook_install().
  */
diff --git a/modules/system/system.module b/modules/system/system.module
index 476094845..7899cf643 100644
--- a/modules/system/system.module
+++ b/modules/system/system.module
@@ -6,15 +6,39 @@
  * Configuration system that lets administrators modify the workings of the site.
  */
 
+/**
+ * The current system version.
+ */
 define('VERSION', '6.0-dev');
+
+/**
+ * Core API compatibility.
+ */
 define('DRUPAL_CORE_COMPATIBILITY', '6.x');
 
+/**
+ * Minimum supported version of PHP.
+ */
 define('DRUPAL_MINIMUM_PHP',    '4.3.3');
-define('DRUPAL_MINIMUM_MYSQL',  '4.1.0'); // If using MySQL
-define('DRUPAL_MINIMUM_PGSQL',  '7.4');   // If using PostgreSQL
-define('DRUPAL_MINIMUM_APACHE', '1.3');   // If using Apache
 
-// Maximum age of temporary files in seconds.
+/**
+ * Minimum supported version of MySQL, if it is used.
+ */
+define('DRUPAL_MINIMUM_MYSQL',  '4.1.0');
+
+/**
+ * Minimum supported version of PostgreSQL, if it is used.
+ */
+define('DRUPAL_MINIMUM_PGSQL',  '7.4');
+
+/**
+ * Minimum supported version of Apache, if it is used.
+ */
+define('DRUPAL_MINIMUM_APACHE', '1.3');
+
+/**
+ * Maximum age of temporary files in seconds.
+ */
 define('DRUPAL_MAXIMUM_TEMP_FILE_AGE', 1440);
 
 /**
@@ -76,6 +100,9 @@ function system_help($path, $arg) {
   }
 }
 
+/**
+ * Implementation of hook_theme().
+ */
 function system_theme() {
   return array_merge(drupal_common_theme(), array(
     'system_theme_select_form' => array(
@@ -119,6 +146,7 @@ function system_theme() {
     ),
   ));
 }
+
 /**
  * Implementation of hook_perm().
  */
@@ -459,6 +487,9 @@ function system_menu() {
   return $items;
 }
 
+/**
+ * Implementation of hook_init().
+ */
 function system_init() {
   // Use the administrative theme if the user is looking at a page in the admin/* path.
   if (arg(0) == 'admin' || (variable_get('node_admin_theme', '0') && arg(0) == 'node' && (arg(1) == 'add' || arg(2) == 'edit'))) {
@@ -504,6 +535,8 @@ function system_user($type, $edit, &$user, $category = NULL) {
 }
 
 /**
+ * Implementation of hook_block().
+ *
  * Generate a block with a promotional link to Drupal.org.
  */
 function system_block($op = 'list', $delta = 0, $edit = NULL) {
@@ -543,6 +576,9 @@ function system_block($op = 'list', $delta = 0, $edit = NULL) {
 
 /**
  * Provide a single block on the administration overview page.
+ *
+ * @param $item
+ *   The menu item to be displayed.
  */
 function system_admin_menu_block($item) {
   $content = array();
@@ -572,7 +608,9 @@ function system_admin_menu_block($item) {
   return $content;
 }
 
-
+/**
+ * Process admin theme form submissions.
+ */
 function system_admin_theme_submit($form, &$form_state) {
   // If we're changing themes, make sure the theme has its blocks initialized.
   if ($form_state['values']['admin_theme'] && $form_state['values']['admin_theme'] != variable_get('admin_theme', '0')) {
@@ -662,6 +700,11 @@ function system_check_directory($form_element) {
 
 /**
  * Retrieves the current status of an array of files in the system table.
+ *
+ * @param $files
+ *   An array of files to check.
+ * @param $type
+ *   The type of the files.
  */
 function system_get_files_database(&$files, $type) {
   // Extract current files from database.
@@ -678,8 +721,13 @@ function system_get_files_database(&$files, $type) {
   }
 }
 
+/**
+ * Prepare defaults for themes.
+ *
+ * @return
+ *   An array of default themes settings.
+ */
 function system_theme_default() {
-  // Prepare defaults for themes.
   return array(
     'regions' => array(
       'left' => 'Left sidebar',
@@ -738,6 +786,9 @@ function system_theme_data() {
 
 /**
  * Helper function to scan and collect theme .info data and their engines.
+ *
+ * @return
+ *   An associative array of themes information.
  */
 function _system_theme_data() {
   static $themes_info = array();
@@ -828,9 +879,16 @@ function _system_theme_data() {
 
 /**
  * Recursive function to find the top level base theme. Themes can inherit
- * templates and function implementations from earlier themes; this function
- * finds the top level parent that has no ancestor, or returns NULL if there
- * isn't a valid parent.
+ * templates and function implementations from earlier themes.
+ *
+ * @param $themes
+ *   An array of available themes.
+ * @param $key
+ *   The name of the theme whose base we are looking for.
+ * @param $used_keys
+ *   A recursion parameter preventing endless loops.
+ * @return
+ *   Returns the top level parent that has no ancestor or returns NULL if there isn't a valid parent.
  */
 function system_find_base_theme($themes, $key, $used_keys = array()) {
   $base_key = $themes[$key]->info['base theme'];
@@ -913,7 +971,14 @@ function system_initialize_theme_blocks($theme) {
 }
 
 /**
- * Add default buttons to a form and set its prefix
+ * Add default buttons to a form and set its prefix.
+ *
+ * @ingroup forms
+ * @see system_settings_form_submit
+ * @param $form
+ *   An associative array containing the structure of the form.
+ * @return
+ *   The form structure.
  */
 function system_settings_form($form) {
   $form['buttons']['submit'] = array('#type' => 'submit', '#value' => t('Save configuration') );
@@ -928,14 +993,11 @@ function system_settings_form($form) {
   return $form;
 }
 
-
-
 /**
  * Execute the system_settings_form.
  *
  * If you want node type configure style handling of your checkboxes,
  * add an array_filter value to your form.
- *
  */
 function system_settings_form_submit($form, &$form_state) {
   $op = isset($form_state['values']['op']) ? $form_state['values']['op'] : '';
@@ -1008,6 +1070,7 @@ function system_node_type($op, $info) {
  * is usually 'confirm') to check if the confirmation was successful or
  * use the regular submit model.
  *
+ * @ingroup forms
  * @param $form
  *   Additional elements to inject into the form, for example hidden elements.
  * @param $question
@@ -1064,6 +1127,14 @@ function system_admin_compact_mode() {
   return (isset($user->admin_compact_mode)) ? $user->admin_compact_mode : variable_get('admin_compact_mode', FALSE);
 }
 
+/**
+ * Generate a list of tasks offered by a specified module.
+ *
+ * @param $module
+ *   Module name.
+ * @return
+ *   An array of task links.
+ */
 function system_get_module_admin_tasks($module) {
   static $items;
 
@@ -1239,6 +1310,10 @@ function system_actions_manage() {
 /**
  * Define the form for the actions overview page.
  *
+ * @see system_actions_manage_form_submit
+ * @ingroup forms
+ * @param $form_state
+ *   An associative array containing the current state of the form; not used.
  * @param $options
  *   An array of configurable actions.
  * @return
@@ -1264,6 +1339,9 @@ function system_actions_manage_form($form_state, $options = array()) {
   return $form;
 }
 
+/**
+ * Process system_actions_manage form submissions.
+ */
 function system_actions_manage_form_submit($form, &$form_state) {
   if ($form_state['values']['action']) {
     $form_state['redirect'] = 'admin/settings/actions/configure/'. $form_state['values']['action'];
@@ -1278,6 +1356,8 @@ function system_actions_manage_form_submit($form, &$form_state) {
  * Because we are combining unknown form elements with the action
  * configuration form, we use actions_ prefix on our elements.
  *
+ * @see system_actions_configure_validate()
+ * @see system_actions_configure_submit()
  * @param $action
  *   md5 hash of action ID or an integer. If it's an md5 hash, we
  *   are creating a new instance. If it's an integer, we're editing
@@ -1354,6 +1434,9 @@ function system_actions_configure($form_state, $action = NULL) {
   return $form;
 }
 
+/**
+ * Validate system_actions_configure form submissions.
+ */
 function system_actions_configure_validate($form, $form_state) {
   $function = actions_function_lookup($form_state['values']['actions_action']) .'_validate';
   // Hand off validation to the action.
@@ -1362,6 +1445,9 @@ function system_actions_configure_validate($form, $form_state) {
   }
 }
 
+/**
+ * Process system_actions_configure form submissions.
+ */
 function system_actions_configure_submit($form, &$form_state) {
   $function = actions_function_lookup($form_state['values']['actions_action']);
   $submit_function = $function .'_submit';
@@ -1379,8 +1465,8 @@ function system_actions_configure_submit($form, &$form_state) {
 /**
  * Create the form for confirmation of deleting an action.
  *
- * @param $aid
- *   The action ID.
+ * @ingroup forms
+ * @see system_actions_delete_form_submit
  */
 function system_actions_delete_form($form_state, $action) {
 
@@ -1397,6 +1483,8 @@ function system_actions_delete_form($form_state, $action) {
 }
 
 /**
+ * Process system_actions_delete form submissions.
+ *
  * Post-deletion operations for action deletion.
  */
 function system_actions_delete_form_submit($form, &$form_state) {
@@ -1408,8 +1496,12 @@ function system_actions_delete_form_submit($form, &$form_state) {
   drupal_set_message(t('Action %action was deleted', array('%action' => $description)));
   $form_state['redirect'] = 'admin/settings/actions/manage';
 }
+
 /**
  * Post-deletion operations for deleting action orphans.
+ *
+ * @param $orphaned
+ *   An array of orphaned actions.
  */
 function system_action_delete_orphans_post($orphaned) {
   foreach ($orphaned as $callback) {
@@ -1419,7 +1511,6 @@ function system_action_delete_orphans_post($orphaned) {
 
 /**
  * Remove actions that are in the database but not supported by any enabled module.
- *
  */
 function system_actions_remove_orphans() {
   actions_synchronize(actions_list(), TRUE);
@@ -1429,6 +1520,8 @@ function system_actions_remove_orphans() {
 /**
  * Return a form definition so the Send email action can be configured.
  *
+ * @see system_send_email_action_validate()
+ * @see system_send_email_action_submit()
  * @param $context
  *   Default values (if we are editing an existing action instance).
  * @return
@@ -1471,6 +1564,9 @@ function system_send_email_action_form($context) {
   return $form;
 }
 
+/**
+ * Validate system_send_email_action form submissions.
+ */
 function system_send_email_action_validate($form, $form_state) {
   $form_values = $form_state['values'];
   // Validate the configuration form.
@@ -1480,6 +1576,9 @@ function system_send_email_action_validate($form, $form_state) {
   }
 }
 
+/**
+ * Process system_send_email_action form submissions.
+ */
 function system_send_email_action_submit($form, $form_state) {
   $form_values = $form_state['values'];
   // Process the HTML form to store configuration. The keyed array that
@@ -1695,6 +1794,9 @@ function system_goto_action($object, $context) {
   drupal_goto($context['url']);
 }
 
+/**
+ * Generate an array of time zones and their local time&date.
+ */
 function _system_zonelist() {
   $timestamp = time();
   $zonelist = array(-11, -10, -9.5, -9, -8, -7, -6, -5, -4, -3.5, -3, -2, -1, 0, 1, 2, 3, 3.5, 4, 5, 5.5, 5.75, 6, 6.5, 7, 8, 9, 9.5, 10, 10.5, 11, 11.5, 12, 12.75, 13, 14);