Issue #1325116 by xenophyle, xjm: Clean up API docs for Aggregator module.

11 files changed, 151 insertions, 90 deletions

diff --git a/modules/aggregator/aggregator-feed-source.tpl.php b/modules/aggregator/aggregator-feed-source.tpl.php
index 6a684bdb7..f9cfa5556 100644
--- a/modules/aggregator/aggregator-feed-source.tpl.php
+++ b/modules/aggregator/aggregator-feed-source.tpl.php
@@ -17,6 +17,8 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_feed_source()
+ *
+ * @ingroup themeable
  */
 ?>
 <div class="feed-source">
diff --git a/modules/aggregator/aggregator-item.tpl.php b/modules/aggregator/aggregator-item.tpl.php
index e9ad1e0d7..74b2284cb 100644
--- a/modules/aggregator/aggregator-item.tpl.php
+++ b/modules/aggregator/aggregator-item.tpl.php
@@ -16,6 +16,8 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_item()
+ *
+ * @ingroup themeable
  */
 ?>
 <div class="feed-item">
diff --git a/modules/aggregator/aggregator-summary-item.tpl.php b/modules/aggregator/aggregator-summary-item.tpl.php
index fcd57c7a4..f9199a52e 100644
--- a/modules/aggregator/aggregator-summary-item.tpl.php
+++ b/modules/aggregator/aggregator-summary-item.tpl.php
@@ -13,6 +13,8 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_summary_item()
+ *
+ * @ingroup themeable
  */
 ?>
 <a href="<?php print $feed_url; ?>"><?php print $feed_title; ?></a>
diff --git a/modules/aggregator/aggregator-summary-items.tpl.php b/modules/aggregator/aggregator-summary-items.tpl.php
index 0e2133a1e..4a0551d71 100644
--- a/modules/aggregator/aggregator-summary-items.tpl.php
+++ b/modules/aggregator/aggregator-summary-items.tpl.php
@@ -14,6 +14,8 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_summary_items()
+ *
+ * @ingroup themeable
  */
 ?>
 <h3><?php print $title; ?></h3>
diff --git a/modules/aggregator/aggregator-wrapper.tpl.php b/modules/aggregator/aggregator-wrapper.tpl.php
index 80b903271..2fa51a70a 100644
--- a/modules/aggregator/aggregator-wrapper.tpl.php
+++ b/modules/aggregator/aggregator-wrapper.tpl.php
@@ -10,6 +10,8 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_wrapper()
+ *
+ * @ingroup themeable
  */
 ?>
 <div id="aggregator">
diff --git a/modules/aggregator/aggregator.admin.inc b/modules/aggregator/aggregator.admin.inc
index 08087afb2..91bc75f34 100644
--- a/modules/aggregator/aggregator.admin.inc
+++ b/modules/aggregator/aggregator.admin.inc
@@ -53,7 +53,11 @@ function aggregator_view() {
 }
 
 /**
- * Form builder; Generate a form to add/edit feed sources.
+ * Form constructor for adding and editing feed sources.
+ *
+ * @param $feed
+ *   If editing a feed, the feed to edit as a PHP stdClass value; if adding a
+ *   new feed, NULL.
  *
  * @ingroup forms
  * @see aggregator_form_feed_validate()
@@ -129,7 +133,9 @@ function aggregator_form_feed($form, &$form_state, stdClass $feed = NULL) {
 }
 
 /**
- * Validate aggregator_form_feed() form submissions.
+ * Form validation handler for aggregator_form_feed().
+ *
+ * @see aggregator_form_feed_submit()
  */
 function aggregator_form_feed_validate($form, &$form_state) {
   if ($form_state['values']['op'] == t('Save')) {
@@ -156,8 +162,9 @@ function aggregator_form_feed_validate($form, &$form_state) {
 }
 
 /**
- * Process aggregator_form_feed() form submissions.
+ * Form submission handler for aggregator_form_feed().
  *
+ * @see aggregator_form_feed_validate()
  * @todo Add delete confirmation dialog.
  */
 function aggregator_form_feed_submit($form, &$form_state) {
@@ -198,6 +205,14 @@ function aggregator_form_feed_submit($form, &$form_state) {
   }
 }
 
+/**
+ * Deletes a feed.
+ *
+ * @param $feed
+ *   An associative array describing the feed to be cleared.
+ *
+ * @see aggregator_admin_remove_feed_submit()
+ */
 function aggregator_admin_remove_feed($form, $form_state, $feed) {
   return confirm_form(
     array(
@@ -215,10 +230,9 @@ function aggregator_admin_remove_feed($form, $form_state, $feed) {
 }
 
 /**
- * Remove all items from a feed and redirect to the overview page.
+ * Form submission handler for aggregator_admin_remove_feed().
  *
- * @param $feed
- *   An associative array describing the feed to be cleared.
+ * Removes all items from a feed and redirects to the overview page.
  */
 function aggregator_admin_remove_feed_submit($form, &$form_state) {
   aggregator_remove($form_state['values']['feed']);
@@ -226,7 +240,7 @@ function aggregator_admin_remove_feed_submit($form, &$form_state) {
 }
 
 /**
- * Form builder; Generate a form to import feeds from OPML.
+ * Form constructor for importing feeds from OPML.
  *
  * @ingroup forms
  * @see aggregator_form_opml_validate()
@@ -280,7 +294,9 @@ function aggregator_form_opml($form, &$form_state) {
 }
 
 /**
- * Validate aggregator_form_opml form submissions.
+ * Form validation handler for aggregator_form_opml().
+ *
+ * @see aggregator_form_opml_submit()
  */
 function aggregator_form_opml_validate($form, &$form_state) {
   // If both fields are empty or filled, cancel.
@@ -295,7 +311,9 @@ function aggregator_form_opml_validate($form, &$form_state) {
 }
 
 /**
- * Process aggregator_form_opml form submissions.
+ * Form submission handler for aggregator_form_opml().
+ *
+ * @see aggregator_form_opml_validate()
  */
 function aggregator_form_opml_submit($form, &$form_state) {
   $data = '';
@@ -347,7 +365,7 @@ function aggregator_form_opml_submit($form, &$form_state) {
 }
 
 /**
- * Parse an OPML file.
+ * Parses an OPML file.
  *
  * Feeds are recognized as <outline> elements with the attributes "text" and
  * "xmlurl" set.
@@ -357,9 +375,9 @@ function aggregator_form_opml_submit($form, &$form_state) {
  *
  * @return
  *   An array of feeds, each an associative array with a "title" and a "url"
- *   element, or NULL if the OPML document failed to be parsed. An empty
- *   array will be returned if the document is valid but contains no feeds, as
- *   some OPML documents do.
+ *   element, or NULL if the OPML document failed to be parsed. An empty array
+ *   will be returned if the document is valid but contains no feeds, as some
+ *   OPML documents do.
  */
 function _aggregator_parse_opml($opml) {
   $feeds = array();
@@ -391,8 +409,9 @@ function aggregator_admin_refresh_feed($feed) {
 }
 
 /**
- * Form builder; Configure the aggregator system.
+ * Form constructor for the aggregator system settings.
  *
+ * @see aggregator_admin_form_submit()
  * @ingroup forms
  */
 function aggregator_admin_form($form, $form_state) {
@@ -500,6 +519,9 @@ function aggregator_admin_form($form, $form_state) {
   return $form;
 }
 
+/**
+ * Form submission handler for aggregator_admin_form().
+ */
 function aggregator_admin_form_submit($form, &$form_state) {
   if (isset($form_state['values']['aggregator_processors'])) {
     $form_state['values']['aggregator_processors'] = array_filter($form_state['values']['aggregator_processors']);
@@ -508,7 +530,13 @@ function aggregator_admin_form_submit($form, &$form_state) {
 }
 
 /**
- * Form builder; Generate a form to add/edit/delete aggregator categories.
+ * Form constructor to add/edit/delete aggregator categories.
+ *
+ * @param $edit
+ *   An associative array containing:
+ *   - title: A string to use for the category title.
+ *   - description: A string to use for the category description.
+ *   - cid: The category ID.
  *
  * @ingroup forms
  * @see aggregator_form_category_validate()
@@ -536,7 +564,9 @@ function aggregator_form_category($form, &$form_state, $edit = array('title' =>
 }
 
 /**
- * Validate aggregator_form_feed form submissions.
+ * Form validation handler for aggregator_form_category().
+ *
+ * @see aggregator_form_category_submit()
  */
 function aggregator_form_category_validate($form, &$form_state) {
   if ($form_state['values']['op'] == t('Save')) {
@@ -554,8 +584,9 @@ function aggregator_form_category_validate($form, &$form_state) {
 }
 
 /**
- * Process aggregator_form_category form submissions.
+ * Form submission handler for aggregator_form_category().
  *
+ * @see aggregator_form_category_validate()
  * @todo Add delete confirmation dialog.
  */
 function aggregator_form_category_submit($form, &$form_state) {
diff --git a/modules/aggregator/aggregator.api.php b/modules/aggregator/aggregator.api.php
index ea1192760..0f708eb85 100644
--- a/modules/aggregator/aggregator.api.php
+++ b/modules/aggregator/aggregator.api.php
@@ -11,21 +11,21 @@
  */
 
 /**
- * Implement this hook to create an alternative fetcher for aggregator module.
+ * Create an alternative fetcher for aggregator.module.
  *
- * A fetcher downloads feed data to a Drupal site. The fetcher is called
- * at the first of the three aggregation stages: data is downloaded by the
- * active fetcher, it is converted to a common format by the active parser and
- * finally, it is passed to all active processors which manipulate or store the
- * data.
+ * A fetcher downloads feed data to a Drupal site. The fetcher is called at the
+ * first of the three aggregation stages: first, data is downloaded by the
+ * active fetcher; second, it is converted to a common format by the active
+ * parser; and finally, it is passed to all active processors, which manipulate
+ * or store the data.
  *
  * Modules that define this hook can be set as active fetcher on
  * admin/config/services/aggregator. Only one fetcher can be active at a time.
  *
  * @param $feed
- *   The $feed object that describes the resource to be downloaded.
- *   $feed->url contains the link to the feed. Download the data at the URL
- *   and expose it to other modules by attaching it to $feed->source_string.
+ *   A feed object representing the resource to be downloaded. $feed->url
+ *   contains the link to the feed. Download the data at the URL and expose it
+ *   to other modules by attaching it to $feed->source_string.
  *
  * @return
  *   TRUE if fetching was successful, FALSE otherwise.
@@ -41,8 +41,7 @@ function hook_aggregator_fetch($feed) {
 }
 
 /**
- * Implement this hook to expose the title and a short description of your
- * fetcher.
+ * Specify the title and short description of your fetcher.
  *
  * The title and the description provided are shown on
  * admin/config/services/aggregator among other places. Use as title the human
@@ -68,19 +67,19 @@ function hook_aggregator_fetch_info() {
 }
 
 /**
- * Implement this hook to create an alternative parser for aggregator module.
+ * Create an alternative parser for aggregator module.
  *
  * A parser converts feed item data to a common format. The parser is called
- * at the second of the three aggregation stages: data is downloaded by the
- * active fetcher, it is converted to a common format by the active parser and
- * finally, it is passed to all active processors which manipulate or store the
- * data.
+ * at the second of the three aggregation stages: first, data is downloaded
+ * by the active fetcher; second, it is converted to a common format by the
+ * active parser; and finally, it is passed to all active processors which
+ * manipulate or store the data.
  *
  * Modules that define this hook can be set as the active parser on
  * admin/config/services/aggregator. Only one parser can be active at a time.
  *
  * @param $feed
- *   An object describing the resource to be parsed: $feed->source_string
+ *   An object describing the resource to be parsed. $feed->source_string
  *   contains the raw feed data. The hook implementation should parse this data
  *   and add the following properties to the $feed object:
  *   - description: The human-readable description of the feed.
@@ -118,8 +117,7 @@ function hook_aggregator_parse($feed) {
 }
 
 /**
- * Implement this hook to expose the title and a short description of your
- * parser.
+ * Specify the title and short description of your parser.
  *
  * The title and the description provided are shown on
  * admin/config/services/aggregator among other places. Use as title the human
@@ -145,23 +143,23 @@ function hook_aggregator_parse_info() {
 }
 
 /**
- * Implement this hook to create a processor for aggregator module.
+ * Create a processor for aggregator.module.
  *
  * A processor acts on parsed feed data. Active processors are called at the
- * third and last of the aggregation stages: data is downloaded by the active
- * fetcher, it is converted to a common format by the active parser and
- * finally, it is passed to all active processors which manipulate or store the
- * data.
+ * third and last of the aggregation stages: first, data is downloaded by the
+ * active fetcher; second, it is converted to a common format by the active
+ * parser; and finally, it is passed to all active processors that manipulate or
+ * store the data.
  *
  * Modules that define this hook can be activated as processor on
  * admin/config/services/aggregator.
  *
  * @param $feed
- *   The $feed object that describes the resource to be processed. $feed->items
- *   contains an array of feed items downloaded and parsed at the parsing
- *   stage. See hook_aggregator_parse() for the basic format of a single item
- *   in the $feed->items array. For the exact format refer to the particular
- *   parser in use.
+ *   A feed object representing the resource to be processed. $feed->items
+ *   contains an array of feed items downloaded and parsed at the parsing stage.
+ *   See hook_aggregator_parse() for the basic format of a single item in the
+ *   $feed->items array. For the exact format refer to the particular parser in
+ *   use.
  *
  * @see hook_aggregator_process_info()
  * @see hook_aggregator_fetch()
@@ -176,17 +174,16 @@ function hook_aggregator_process($feed) {
 }
 
 /**
- * Implement this hook to expose the title and a short description of your
- * processor.
+ * Specify the title and short description of your processor.
  *
  * The title and the description provided are shown most importantly on
  * admin/config/services/aggregator. Use as title the natural name of the
- * processor and as description a brief (40 to 80 characters) explanation of
- * the functionality.
+ * processor and as description a brief (40 to 80 characters) explanation of the
+ * functionality.
  *
- * This hook is only called if your module implements
- * hook_aggregator_process(). If this hook is not implemented aggregator
- * will use your module's file name as title and there will be no description.
+ * This hook is only called if your module implements hook_aggregator_process().
+ * If this hook is not implemented aggregator will use your module's file name
+ * as title and there will be no description.
  *
  * @return
  *   An associative array defining a title and a description string.
@@ -203,8 +200,7 @@ function hook_aggregator_process_info($feed) {
 }
 
 /**
- * Implement this hook to remove stored data if a feed is being deleted or a
- * feed's items are being removed.
+ * Remove stored feed data.
  *
  * Aggregator calls this hook if either a feed is deleted or a user clicks on
  * "remove items".
diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module
index 9a78d971e..9319ad9b8 100644
--- a/modules/aggregator/aggregator.module
+++ b/modules/aggregator/aggregator.module
@@ -266,7 +266,10 @@ function aggregator_menu() {
 }
 
 /**
- * Title callback for aggregatory category pages.
+ * Title callback: Returns a title for aggregatory category pages.
+ *
+ * @param $category
+ *   An aggregator category.
  *
  * @return
  *   An aggregator category title.
@@ -276,11 +279,11 @@ function _aggregator_category_title($category) {
 }
 
 /**
- * Find out whether there are any aggregator categories.
+ * Determines whether there are any aggregator categories.
  *
  * @return
- *   TRUE if there is at least one category and the user has access to them, FALSE
- *   otherwise.
+ *   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') && (bool) db_query_range('SELECT 1 FROM {aggregator_category}', 0, 1)->fetchField();
@@ -425,7 +428,7 @@ function aggregator_block_view($delta = '') {
 }
 
 /**
- * Add/edit/delete aggregator categories.
+ * Adds/edits/deletes aggregator categories.
  *
  * @param $edit
  *   An associative array describing the category to be added/edited/deleted.
@@ -574,6 +577,12 @@ function aggregator_remove($feed) {
     ->execute();
 }
 
+/**
+ * Gets the fetcher, parser, and processors.
+ *
+ * @return
+ *   An array containing the fetcher, parser, and processors.
+ */
 function _aggregator_get_variables() {
   // Fetch the feed.
   $fetcher = variable_get('aggregator_fetcher', 'aggregator');
@@ -660,10 +669,11 @@ function aggregator_refresh($feed) {
 }
 
 /**
- * Load an aggregator feed.
+ * Loads an aggregator feed.
  *
  * @param $fid
  *   The feed id.
+ *
  * @return
  *   An object describing the feed.
  */
@@ -677,10 +687,11 @@ function aggregator_feed_load($fid) {
 }
 
 /**
- * Load an aggregator category.
+ * Loads an aggregator category.
  *
  * @param $cid
  *   The category id.
+ *
  * @return
  *   An associative array describing the category.
  */
@@ -709,10 +720,11 @@ function theme_aggregator_block_item($variables) {
 }
 
 /**
- * Safely render HTML content, as allowed.
+ * Safely renders HTML content, as allowed.
  *
  * @param $value
  *   The content to be filtered.
+ *
  * @return
  *   The filtered content.
  */
@@ -721,14 +733,13 @@ function aggregator_filter_xss($value) {
 }
 
 /**
- * Check and sanitize aggregator configuration.
+ * Checks and sanitizes the aggregator configuration.
  *
- * Goes through all fetchers, parsers and processors and checks whether they are
- * available.
- * If one is missing resets to standard configuration.
+ * Goes through all fetchers, parsers and processors and checks whether they
+ * are available. If one is missing resets to standard configuration.
  *
  * @return
- *   TRUE if this function reset the configuration FALSE if not.
+ *   TRUE if this function resets the configuration; FALSE if not.
  */
 function aggregator_sanitize_configuration() {
   $reset = FALSE;
@@ -759,6 +770,7 @@ function aggregator_sanitize_configuration() {
  *
  * @param $count
  *   Items count.
+ *
  * @return
  *   Plural-formatted "@count items"
  */
diff --git a/modules/aggregator/aggregator.pages.inc b/modules/aggregator/aggregator.pages.inc
index 8074ae82e..cd1c4cb2c 100644
--- a/modules/aggregator/aggregator.pages.inc
+++ b/modules/aggregator/aggregator.pages.inc
@@ -160,11 +160,13 @@ function aggregator_feed_items_load($type, $data = NULL) {
  * @param $items
  *   The items to be listed.
  * @param $op
- *   Which form should be added to the items. Only 'categorize' is now recognized.
+ *   Which form should be added to the items. Only 'categorize' is now
+ *   recognized.
  * @param $feed_source
  *   The feed source URL.
+ *
  * @return
- *   The items HTML.
+ *   The rendered list of items for a feed.
  */
 function _aggregator_page_list($items, $op, $feed_source = '') {
   if (user_access('administer news feeds') && ($op == 'categorize')) {
@@ -184,14 +186,13 @@ function _aggregator_page_list($items, $op, $feed_source = '') {
 }
 
 /**
- * Form builder; build the page list form.
+ * Form constructor to 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_submit()
  */
@@ -236,7 +237,7 @@ function aggregator_categorize_items($items, $feed_source = '') {
 }
 
 /**
- * Process aggregator_categorize_items() form submissions.
+ * Form submission handler for aggregator_categorize_items().
  */
 function aggregator_categorize_items_submit($form, &$form_state) {
   if (!empty($form_state['values']['categories'])) {
@@ -293,7 +294,7 @@ function theme_aggregator_categorize_items($variables) {
 }
 
 /**
- * Process variables for aggregator-wrapper.tpl.php.
+ * Processes variables for aggregator-wrapper.tpl.php.
  *
  * @see aggregator-wrapper.tpl.php
  */
@@ -302,7 +303,7 @@ function template_preprocess_aggregator_wrapper(&$variables) {
 }
 
 /**
- * Process variables for aggregator-item.tpl.php.
+ * Processes variables for aggregator-item.tpl.php.
  *
  * @see aggregator-item.tpl.php
  */
@@ -499,7 +500,7 @@ function theme_aggregator_page_opml($variables) {
 }
 
 /**
- * Process variables for aggregator-summary-items.tpl.php.
+ * Processes variables for aggregator-summary-items.tpl.php.
  *
  * @see aggregator-summary-items.tpl.php
  */
@@ -510,7 +511,7 @@ function template_preprocess_aggregator_summary_items(&$variables) {
 }
 
 /**
- * Process variables for aggregator-summary-item.tpl.php.
+ * Processes variables for aggregator-summary-item.tpl.php.
  *
  * @see aggregator-summary-item.tpl.php
  */
@@ -530,7 +531,7 @@ function template_preprocess_aggregator_summary_item(&$variables) {
 }
 
 /**
- * Process variables for aggregator-feed-source.tpl.php.
+ * Processes variables for aggregator-feed-source.tpl.php.
  *
  * @see aggregator-feed-source.tpl.php
  */
diff --git a/modules/aggregator/aggregator.parser.inc b/modules/aggregator/aggregator.parser.inc
index e9f1d2e8a..91fbe3aa1 100644
--- a/modules/aggregator/aggregator.parser.inc
+++ b/modules/aggregator/aggregator.parser.inc
@@ -54,12 +54,13 @@ function aggregator_aggregator_parse($feed) {
 }
 
 /**
- * Parse a feed and store its items.
+ * Parses a feed and stores its items.
  *
  * @param $data
  *   The feed data.
  * @param $feed
  *   An object describing the feed to be parsed.
+ *
  * @return
  *   FALSE on error, TRUE otherwise.
  */
@@ -164,7 +165,9 @@ function aggregator_parse_feed(&$data, $feed) {
 }
 
 /**
- * Callback function used by the XML parser.
+ * Performs an action when an opening tag is encountered.
+ *
+ * Callback function used by xml_parse() within aggregator_parse_feed().
  */
 function aggregator_element_start($parser, $name, $attributes) {
   global $item, $element, $tag, $items, $channel;
@@ -212,7 +215,9 @@ function aggregator_element_start($parser, $name, $attributes) {
 }
 
 /**
- * Call-back function used by the XML parser.
+ * Performs an action when a closing tag is encountered.
+ *
+ * Callback function used by xml_parse() within aggregator_parse_feed().
  */
 function aggregator_element_end($parser, $name) {
   global $element;
@@ -234,7 +239,9 @@ function aggregator_element_end($parser, $name) {
 }
 
 /**
- * Callback function used by the XML parser.
+ * Performs an action when data is encountered.
+ *
+ * Callback function used by xml_parse() within aggregator_parse_feed().
  */
 function aggregator_element_data($parser, $data) {
   global $channel, $element, $items, $item, $image, $tag;
@@ -281,14 +288,15 @@ function aggregator_element_data($parser, $data) {
 }
 
 /**
- * Parse the W3C date/time format, a subset of ISO 8601.
+ * Parses the W3C date/time format, a subset of ISO 8601.
  *
- * PHP date parsing functions do not handle this format.
- * See http://www.w3.org/TR/NOTE-datetime for more information.
- * Originally from MagpieRSS (http://magpierss.sourceforge.net/).
+ * PHP date parsing functions do not handle this format. 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 FALSE if not.
  */
diff --git a/modules/aggregator/aggregator.processor.inc b/modules/aggregator/aggregator.processor.inc
index 79261b618..5464d66e1 100644
--- a/modules/aggregator/aggregator.processor.inc
+++ b/modules/aggregator/aggregator.processor.inc
@@ -126,14 +126,17 @@ function aggregator_form_aggregator_admin_form_alter(&$form, $form_state) {
 }
 
 /**
- * Helper function for teaser length choices.
+ * Creates display text for teaser length option values.
+ *
+ * Callback for drupal_map_assoc() within
+ * aggregator_form_aggregator_admin_form_alter().
  */
 function _aggregator_characters($length) {
   return ($length == 0) ? t('Unlimited') : format_plural($length, '1 character', '@count characters');
 }
 
 /**
- * Add/edit/delete an aggregator item.
+ * Adds/edits/deletes an aggregator item.
  *
  * @param $edit
  *   An associative array describing the item to be added/edited/deleted.
@@ -175,7 +178,7 @@ function aggregator_save_item($edit) {
 }
 
 /**
- * Expire feed items on $feed that are older than aggregator_clear.
+ * Expires items from a feed depending on expiration settings.
  *
  * @param $feed
  *   Object describing feed.