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

3 files changed, 164 insertions, 26 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) {