Commit 2ca0aba9 authored by catch's avatar catch
Browse files

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

parent e80124f3
......@@ -17,6 +17,8 @@
*
* @see template_preprocess()
* @see template_preprocess_aggregator_feed_source()
*
* @ingroup themeable
*/
?>
<div class="feed-source">
......
......@@ -16,6 +16,8 @@
*
* @see template_preprocess()
* @see template_preprocess_aggregator_item()
*
* @ingroup themeable
*/
?>
<div class="feed-item">
......
......@@ -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>
......
......@@ -14,6 +14,8 @@
*
* @see template_preprocess()
* @see template_preprocess_aggregator_summary_items()
*
* @ingroup themeable
*/
?>
<h3><?php print $title; ?></h3>
......
......@@ -10,6 +10,8 @@
*
* @see template_preprocess()
* @see template_preprocess_aggregator_wrapper()
*
* @ingroup themeable
*/
?>
<div class="<?php print $classes; ?>">
......
......@@ -6,7 +6,11 @@
*/
/**
* Menu callback; displays the aggregator administration page.
* Page callback: Displays the aggregator administration page.
*
* Path: admin/config/services/aggregator
*
* @see aggregator_menu()
*/
function aggregator_admin_overview() {
return aggregator_view();
......@@ -53,9 +57,16 @@ function aggregator_view() {
}
/**
* Form builder; Generate a form to add/edit feed sources.
* Page callback: Form constructor for adding and editing feed sources.
*
* Path: admin/config/services/aggregator/add/feed
*
* @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_menu()
* @see aggregator_form_feed_validate()
* @see aggregator_form_feed_submit()
*/
......@@ -129,7 +140,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 +169,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 +212,17 @@ function aggregator_form_feed_submit($form, &$form_state) {
}
}
/**
* Page callback: Deletes a feed.
*
* Path: admin/config/services/aggregator/remove/%aggregator_feed
*
* @param $feed
* An associative array describing the feed to be cleared.
*
* @see aggregator_admin_remove_feed_submit()
* @see aggregator_menu()
*/
function aggregator_admin_remove_feed($form, $form_state, $feed) {
return confirm_form(
array(
......@@ -215,10 +240,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,9 +250,12 @@ function aggregator_admin_remove_feed_submit($form, &$form_state) {
}
/**
* Form builder; Generate a form to import feeds from OPML.
* Page callback: Form constructor for importing feeds from OPML.
*
* Path: admin/config/services/aggregator/add/opml
*
* @ingroup forms
* @see aggregator_menu()
* @see aggregator_form_opml_validate()
* @see aggregator_form_opml_submit()
*/
......@@ -280,7 +307,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 +324,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 +378,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 +388,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();
......@@ -380,10 +411,14 @@ function _aggregator_parse_opml($opml) {
}
/**
* Menu callback; refreshes a feed, then redirects to the overview page.
* Page callback: Refreshes a feed, then redirects to the overview page.
*
* Path: admin/config/services/aggregator/update/%aggregator_feed
*
* @param $feed
* An object describing the feed to be refreshed.
*
* @see aggregator_menu()
*/
function aggregator_admin_refresh_feed($feed) {
aggregator_refresh($feed);
......@@ -391,8 +426,12 @@ function aggregator_admin_refresh_feed($feed) {
}
/**
* Form builder; Configure the aggregator system.
* Page callback: Form constructor for the aggregator system settings.
*
* Path: admin/config/services/aggregator/settings
*
* @see aggregator_menu()
* @see aggregator_admin_form_submit()
* @ingroup forms
*/
function aggregator_admin_form($form, $form_state) {
......@@ -500,6 +539,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,9 +550,18 @@ function aggregator_admin_form_submit($form, &$form_state) {
}
/**
* Form builder; Generate a form to add/edit/delete aggregator categories.
* Page callback: Form constructor to add/edit/delete aggregator categories.
*
* Path: admin/config/services/aggregator/add/category
*
* @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_menu()
* @see aggregator_form_category_validate()
* @see aggregator_form_category_submit()
*/
......@@ -536,7 +587,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 +607,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) {
......
......@@ -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".
......
......@@ -266,7 +266,12 @@ function aggregator_menu() {
}
/**
* Title callback for aggregatory category pages.
* Title callback: Returns a title for aggregatory category pages.
*
* Path: aggregator/categories/%aggregator_category
*
* @param $category
* An aggregator category.
*
* @return
* An aggregator category title.
......@@ -276,11 +281,13 @@ function _aggregator_category_title($category) {
}
/**
* Find out whether there are any aggregator categories.
* Access callback: Determines whether there are any aggregator categories.
*
* Path: 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 +432,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.
......@@ -474,10 +481,11 @@ function aggregator_save_category($edit) {
}
/**
* Add/edit/delete an aggregator feed.
* Adds/edits/deletes an aggregator feed.
*
* @param $edit
* An associative array describing the feed to be added/edited/deleted.
*
* @return
* The ID of the feed.
*/
......@@ -574,6 +582,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 +674,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 +692,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 +725,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 +738,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 +775,7 @@ function aggregator_sanitize_configuration() {
*
* @param $count
* Items count.
*
* @return
* Plural-formatted "@count items"
*/
......
......@@ -6,10 +6,11 @@
*/
/**
* Menu callback; displays the most recent items gathered from any feed.
* Page callback: Displays the most recent items gathered from any feed.
*
* @return
* The items HTML.
* Path: aggregator
*
* @see aggregator_menu()
*/
function aggregator_page_last() {
drupal_add_feed('aggregator/rss', variable_get('site_name', 'Drupal') . ' ' . t('aggregator'));
......@@ -20,13 +21,14 @@ function aggregator_page_last() {
}
/**
* Menu callback; displays all the items captured from a particular feed.
* Page callback: Displays all the items captured from a particular feed.
*
* Path: aggregator/sources/%aggregator_feed
*
* @param $feed
* The feed for which to display all items.
*
* @return
* The rendered list of items for a feed.
* @see aggregator_menu()
*/
function aggregator_page_source($feed) {
drupal_set_title($feed->title);
......@@ -40,28 +42,31 @@ function aggregator_page_source($feed) {
}
/**
* Menu callback; displays a form with all items captured from a feed.
* Page callback: Form constructor to show all items captured from a feed.
*
* Path: aggregator/sources/%aggregator_feed/categorize
*
* @param $feed
* The feed for which to list all the aggregated items.
*
* @return
* The rendered list of items for a feed.
*
* @see aggregator_menu()
* @see aggregator_page_source()
* @ingroup forms
*/
function aggregator_page_source_form($form, $form_state, $feed) {
return aggregator_page_source($feed);
}
/**
* Menu callback; displays all the items aggregated in a particular category.
* Page callback: Form constructor to list items aggregated in a category.
*
* Path: aggregator/categories
*
* @param $category
* The category for which to list all the aggregated items.
*
* @return
* The rendered list of items for a category.
* @see aggregator_menu()
* @ingroup forms
*/
function aggregator_page_category($category) {
drupal_add_feed('aggregator/rss/' . $category['cid'], variable_get('site_name', 'Drupal') . ' ' . t('aggregator - @title', array('@title' => $category['title'])));
......@@ -74,15 +79,16 @@ function aggregator_page_category($category) {
}
/**
* Menu callback; displays a form containing items aggregated in a category.
* Page callback: Form constructor to list items aggregated in a category.
*
* Path: aggregator/categories/%aggregator_category/categorize
*
* @param $category
* The category for which to list all the aggregated items.
*
* @return
* The rendered list of items for a category.
*
* @see aggregator_menu()
* @see aggregator_page_category()
* @ingroup forms
*/
function aggregator_page_category_form($form, $form_state, $category) {
return aggregator_page_category($category);
......@@ -160,11 +166,13 @@ function aggregator_load_feed_items($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.
*/