diff --git a/modules/aggregator/aggregator-rtl.css b/modules/aggregator/aggregator-rtl.css index ea59ca3a19f10c0103741d0d7f02ca6d1406fc28..057d01565853080178de063df2e6dc65966dd5bd 100644 --- a/modules/aggregator/aggregator-rtl.css +++ b/modules/aggregator/aggregator-rtl.css @@ -1,3 +1,6 @@ +/** + * Right-to-Left styles for theme in the Aggregator module. + */ #aggregator .feed-source .feed-icon { float: left; diff --git a/modules/aggregator/aggregator.admin.inc b/modules/aggregator/aggregator.admin.inc index 8b817c0fafc4fdce57952e609c678f4b469fd121..443facb129950a14dc9299b1269e13c08e7bacea 100644 --- a/modules/aggregator/aggregator.admin.inc +++ b/modules/aggregator/aggregator.admin.inc @@ -2,11 +2,11 @@ /** * @file - * Admin page callbacks for the aggregator module. + * Administration page callbacks for the Aggregator module. */ /** - * Menu callback; displays the aggregator administration page. + * Page callback: Displays the Aggregator module administration page. */ function aggregator_admin_overview() { return aggregator_view(); @@ -16,7 +16,7 @@ function aggregator_admin_overview() { * Displays the aggregator administration page. * * @return - * The page HTML. + * A HTML-formatted string with administration page content. */ function aggregator_view() { $result = db_query('SELECT f.fid, f.title, f.url, f.refresh, f.checked, f.link, f.description, f.hash, f.etag, f.modified, f.image, f.block, 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.hash, f.etag, f.modified, f.image, f.block ORDER BY f.title'); @@ -56,8 +56,8 @@ function aggregator_view() { * 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. + * (optional) If editing a feed, the feed to edit as a PHP stdClass value; if + * adding a new feed, NULL. Defaults to NULL. * * @ingroup forms * @see aggregator_form_feed_validate() @@ -165,6 +165,7 @@ function aggregator_form_feed_validate($form, &$form_state) { * 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) { @@ -398,7 +399,7 @@ 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. * * @param $feed * An object describing the feed to be refreshed. @@ -590,6 +591,7 @@ function aggregator_form_category_validate($form, &$form_state) { * 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.css b/modules/aggregator/aggregator.css index 13c58ffe70eeeb58f82954a4f75c6c224c1c7633..4285631e87aa657329740a18f33b3b0f717c8386 100644 --- a/modules/aggregator/aggregator.css +++ b/modules/aggregator/aggregator.css @@ -1,3 +1,6 @@ +/** + * Styles for theme in the Aggregator module. + */ #aggregator .feed-source .feed-title { margin-top: 0; diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module index 93457c68de0adf91d0c2fba6555ae6a3ee065b1e..70f8c5cd828bd63c096419b35336ec1626ca09d7 100644 --- a/modules/aggregator/aggregator.module +++ b/modules/aggregator/aggregator.module @@ -266,13 +266,13 @@ function aggregator_menu() { } /** - * Title callback: Returns a title for aggregatory category pages. + * Title callback: Returns a title for aggregator category pages. * * @param $category * An aggregator category. * * @return - * An aggregator category title. + * A string with the aggregator category title. */ function _aggregator_category_title($category) { return $category['title']; @@ -723,7 +723,7 @@ function theme_aggregator_block_item($variables) { } /** - * Safely renders HTML content, as allowed. + * Renders the HTML content safely, as allowed. * * @param $value * The content to be filtered. @@ -739,7 +739,7 @@ function aggregator_filter_xss($value) { * 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. + * are available. If one is missing, resets to standard configuration. * * @return * TRUE if this function resets the configuration; FALSE if not. @@ -775,7 +775,7 @@ function aggregator_sanitize_configuration() { * Items count. * * @return - * Plural-formatted "@count items" + * A string that is plural-formatted as "@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 cd1c4cb2c08cc0600bc43c248b36aed654c538d5..bfba3fffb0dfe8ff6bd28ceafbf3fd3ac3e40110 100644 --- a/modules/aggregator/aggregator.pages.inc +++ b/modules/aggregator/aggregator.pages.inc @@ -2,14 +2,14 @@ /** * @file - * User page callbacks for the aggregator module. + * User page callbacks for the Aggregator module. */ /** - * 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. + * The rendered list of items for the feed. */ function aggregator_page_last() { drupal_add_feed('aggregator/rss', variable_get('site_name', 'Drupal') . ' ' . t('aggregator')); @@ -20,13 +20,15 @@ function aggregator_page_last() { } /** - * Menu callback; displays all the items captured from a particular feed. + * Page callback: Displays all the items captured from the particular 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,13 +42,13 @@ function aggregator_page_source($feed) { } /** - * Menu callback; displays a form with all items captured from a feed. + * Page callback: Displays a form with all items captured from a feed. * * @param $feed - * The feed for which to list all the aggregated items. + * The feed for which to list all of the aggregated items. * * @return - * The rendered list of items for a feed. + * The rendered list of items for the feed. * * @see aggregator_page_source() */ @@ -55,13 +57,13 @@ function aggregator_page_source_form($form, $form_state, $feed) { } /** - * Menu callback; displays all the items aggregated in a particular category. + * Page callback: Displays all the items aggregated in a particular category. * * @param $category - * The category for which to list all the aggregated items. + * The category for which to list all of the aggregated items. * * @return -* The rendered list of items for a category. + * The rendered list of items for the feed. */ 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,13 +76,13 @@ function aggregator_page_category($category) { } /** - * Menu callback; displays a form containing items aggregated in a category. + * Page callback: Displays a form containing items aggregated in a category. * * @param $category - * The category for which to list all the aggregated items. + * The category for which to list all of the aggregated items. * * @return -* The rendered list of items for a category. + * The rendered list of items for the feed. * * @see aggregator_page_category() */ @@ -166,7 +168,7 @@ function aggregator_feed_items_load($type, $data = NULL) { * The feed source URL. * * @return - * The rendered list of items for a feed. + * The rendered list of items for the feed. */ function _aggregator_page_list($items, $op, $feed_source = '') { if (user_access('administer news feeds') && ($op == 'categorize')) { @@ -191,10 +193,14 @@ function _aggregator_page_list($items, $op, $feed_source = '') { * @param $items * An array of the feed items. * @param $feed_source - * The feed source URL. + * (optional) The feed source URL. Defaults to an empty string. + * + * @return array + * An array of FAPI elements. * - * @ingroup forms * @see aggregator_categorize_items_submit() + * @see theme_aggregator_categorize_items() + * @ingroup forms */ function aggregator_categorize_items($items, $feed_source = '') { $form['#submit'][] = 'aggregator_categorize_items_submit'; @@ -334,7 +340,12 @@ function template_preprocess_aggregator_item(&$variables) { } /** - * Menu callback; displays all the feeds used by the aggregator. + * Page callback: Displays all the feeds used by the aggregator. + * + * @return + * An HTML-formatted string. + * + * @see aggregator_menu() */ function aggregator_page_sources() { $result = db_query('SELECT f.fid, f.title, f.description, f.image, MAX(i.timestamp) AS last FROM {aggregator_feed} f LEFT JOIN {aggregator_item} i ON f.fid = i.fid GROUP BY f.fid, f.title, f.description, f.image ORDER BY last DESC, f.title'); @@ -358,7 +369,12 @@ function aggregator_page_sources() { } /** - * Menu callback; displays all the categories used by the aggregator. + * Page callback: Displays all the categories used by the Aggregator module. + * + * @return string + * An HTML formatted string. + * + * @see aggregator_menu() */ function aggregator_page_categories() { $result = db_query('SELECT c.cid, c.title, c.description FROM {aggregator_category} c LEFT JOIN {aggregator_category_item} ci ON c.cid = ci.cid LEFT JOIN {aggregator_item} i ON ci.iid = i.iid GROUP BY c.cid, c.title, c.description'); @@ -380,7 +396,10 @@ function aggregator_page_categories() { } /** - * Menu callback; generate an RSS 0.92 feed of aggregator items or categories. + * Page callback: Generates an RSS 0.92 feed of aggregator items or categories. + * + * @return string + * An HTML formatted string. */ function aggregator_page_rss() { $result = NULL; @@ -448,12 +467,14 @@ function theme_aggregator_page_rss($variables) { } /** - * Menu callback; generates an OPML representation of all feeds. + * Page 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. + * (optional) If set, feeds are exported only from a category with this ID. + * Otherwise, all feeds are exported. Defaults to NULL. + * * @return - * The output XML. + * An OPML formatted string. */ function aggregator_page_opml($cid = NULL) { if ($cid) { @@ -468,14 +489,12 @@ function aggregator_page_opml($cid = NULL) { } /** - * Prints the OPML page for a feed. + * Prints the OPML page for the feed. * * @param $variables * An associative array containing: * - feeds: An array of the feeds to theme. * - * @return void - * * @ingroup themeable */ function theme_aggregator_page_opml($variables) { diff --git a/modules/aggregator/aggregator.processor.inc b/modules/aggregator/aggregator.processor.inc index 3f1319c8c118de093cbd48206a4474564df14d11..44ed549962a041390a2a0a0029579b0810a91fcf 100644 --- a/modules/aggregator/aggregator.processor.inc +++ b/modules/aggregator/aggregator.processor.inc @@ -131,6 +131,12 @@ function aggregator_form_aggregator_admin_form_alter(&$form, $form_state) { * * Callback for drupal_map_assoc() within * aggregator_form_aggregator_admin_form_alter(). + * + * @param $length + * The desired length of teaser text, in bytes. + * + * @return + * A translated string explaining the teaser string length. */ function _aggregator_characters($length) { return ($length == 0) ? t('Unlimited') : format_plural($length, '1 character', '@count characters'); diff --git a/modules/aggregator/aggregator.test b/modules/aggregator/aggregator.test index eff31020f104f7b879974de4ded83ff59db49b50..8b95d6e379bb50554ef9e79a77b564f5b5fa5cca 100644 --- a/modules/aggregator/aggregator.test +++ b/modules/aggregator/aggregator.test @@ -5,6 +5,9 @@ * Tests for aggregator.module. */ +/** + * Defines a base class for testing the Aggregator module. + */ class AggregatorTestCase extends DrupalWebTestCase { function setUp() { parent::setUp('aggregator', 'aggregator_test'); @@ -13,10 +16,15 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Create an aggregator feed (simulate form submission on admin/config/services/aggregator/add/feed). + * Creates an aggregator feed. + * + * This method simulates the form submission on path + * admin/config/services/aggregator/add/feed. * * @param $feed_url - * If given, feed will be created with this URL, otherwise /rss.xml will be used. + * (optional) If given, feed will be created with this URL, otherwise + * /rss.xml will be used. Defaults to NULL. + * * @return $feed * Full feed object if possible. * @@ -33,7 +41,7 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Delete an aggregator feed. + * Deletes an aggregator feed. * * @param $feed * Feed object representing the feed. @@ -44,10 +52,11 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Return a randomly generated feed edit array. + * Returns a randomly generated feed edit array. * * @param $feed_url - * If given, feed will be created with this URL, otherwise /rss.xml will be used. + * (optional) If given, feed will be created with this URL, otherwise + * /rss.xml will be used. Defaults to NULL. * @return * A feed array. */ @@ -68,7 +77,7 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Return the count of the randomly created feed array. + * Returns the count of the randomly created feed array. * * @return * Number of feed items on default feed created by createFeed(). @@ -80,10 +89,13 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Update feed items (simulate click to admin/config/services/aggregator/update/$fid). + * Updates the feed items. + * + * This method simulates a click to + * admin/config/services/aggregator/update/$fid. * * @param $feed - * Feed object representing the feed. + * Feed object representing the feed, passed by reference. * @param $expected_count * Expected number of feed items. */ @@ -112,7 +124,7 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Confirm item removal from a feed. + * Confirms an item removal from a feed. * * @param $feed * Feed object representing the feed. @@ -123,7 +135,7 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Add and remove feed items and ensure that the count is zero. + * Adds and removes feed items and ensure that the count is zero. * * @param $feed * Feed object representing the feed. @@ -140,7 +152,7 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Pull feed categories from aggregator_category_feed table. + * Pulls feed categories from {aggregator_category_feed} table. * * @param $feed * Feed object representing the feed. @@ -154,7 +166,11 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Pull categories from aggregator_category table. + * Pulls categories from {aggregator_category} table. + * + * @return + * An associative array keyed by category ID and values are set to the + * category names. */ function getCategories() { $categories = array(); @@ -165,14 +181,14 @@ class AggregatorTestCase extends DrupalWebTestCase { return $categories; } - /** - * Check if the feed name and URL is unique. + * Checks whether the feed name and URL are unique. * * @param $feed_name * String containing the feed name to check. * @param $feed_url * String containing the feed URL to check. + * * @return * TRUE if feed is unique. */ @@ -182,10 +198,11 @@ class AggregatorTestCase extends DrupalWebTestCase { } /** - * Create a valid OPML file from an array of feeds. + * Creates a valid OPML file from an array of feeds. * * @param $feeds * An array of feeds. + * * @return * Path to valid OPML file. */ @@ -223,7 +240,7 @@ EOF; } /** - * Create an invalid OPML file. + * Creates an invalid OPML file. * * @return * Path to invalid OPML file. @@ -240,7 +257,7 @@ EOF; } /** - * Create a valid but empty OPML file. + * Creates a valid but empty OPML file. * * @return * Path to empty OPML file. @@ -275,7 +292,7 @@ EOF; * Creates sample article nodes. * * @param $count - * (optional) The number of nodes to generate. + * (optional) The number of nodes to generate. Defaults to five. */ function createSampleNodes($count = 5) { $langcode = LANGUAGE_NONE; @@ -290,7 +307,7 @@ EOF; } /** - * Tests aggregator configuration settings. + * Tests functionality of the configuration settings in the Aggregator module. */ class AggregatorConfigurationTestCase extends AggregatorTestCase { public static function getInfo() { @@ -321,6 +338,9 @@ class AggregatorConfigurationTestCase extends AggregatorTestCase { } } +/** + * Tests adding aggregator feeds. + */ class AddFeedTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -331,7 +351,7 @@ class AddFeedTestCase extends AggregatorTestCase { } /** - * Create a feed, ensure that it is unique, check the source, and delete the feed. + * Creates and ensures that a feed is unique, checks source, and deletes feed. */ function testAddFeed() { $feed = $this->createFeed(); @@ -381,6 +401,9 @@ class AddFeedTestCase extends AggregatorTestCase { } } +/** + * Tests the categorize feed functionality in the Aggregator module. + */ class CategorizeFeedTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -391,7 +414,7 @@ class CategorizeFeedTestCase extends AggregatorTestCase { } /** - * Create a feed and make sure you can add more than one category to it. + * Creates a feed and makes sure you can add more than one category to it. */ function testCategorizeFeed() { @@ -424,6 +447,9 @@ class CategorizeFeedTestCase extends AggregatorTestCase { } } +/** + * Tests functionality of updating the feed in the Aggregator module. + */ class UpdateFeedTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -434,7 +460,7 @@ class UpdateFeedTestCase extends AggregatorTestCase { } /** - * Create a feed and attempt to update it. + * Creates a feed and attempts to update it. */ function testUpdateFeed() { $remamining_fields = array('title', 'url', ''); @@ -466,6 +492,9 @@ class UpdateFeedTestCase extends AggregatorTestCase { } } +/** + * Tests functionality for removing feeds in the Aggregator module. + */ class RemoveFeedTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -476,7 +505,7 @@ class RemoveFeedTestCase extends AggregatorTestCase { } /** - * Remove a feed and ensure that all it services are removed. + * Removes a feed and ensures that all of its services are removed. */ function testRemoveFeed() { $feed = $this->createFeed(); @@ -494,6 +523,9 @@ class RemoveFeedTestCase extends AggregatorTestCase { } } +/** + * Tests functionality of updating a feed item in the Aggregator module. + */ class UpdateFeedItemTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -504,7 +536,7 @@ class UpdateFeedItemTestCase extends AggregatorTestCase { } /** - * Test running "update items" from the 'admin/config/services/aggregator' page. + * Tests running "update items" from 'admin/config/services/aggregator' page. */ function testUpdateFeedItem() { $this->createSampleNodes(); @@ -564,7 +596,7 @@ class RemoveFeedItemTestCase extends AggregatorTestCase { } /** - * Test running "remove items" from the 'admin/config/services/aggregator' page. + * Tests running "remove items" from 'admin/config/services/aggregator' page. */ function testRemoveFeedItem() { // Create a bunch of test feeds. @@ -592,6 +624,9 @@ class RemoveFeedItemTestCase extends AggregatorTestCase { } } +/** + * Tests categorization functionality in the Aggregator module. + */ class CategorizeFeedItemTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -602,6 +637,8 @@ class CategorizeFeedItemTestCase extends AggregatorTestCase { } /** + * Checks that children of a feed inherit a defined category. + * * If a feed has a category, make sure that the children inherit that * categorization. */ @@ -649,6 +686,9 @@ class CategorizeFeedItemTestCase extends AggregatorTestCase { } } +/** + * Tests importing feeds from OPML functionality for the Aggregator module. + */ class ImportOPMLTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -659,7 +699,7 @@ class ImportOPMLTestCase extends AggregatorTestCase { } /** - * Open OPML import form. + * Opens OPML import form. */ function openImportForm() { db_delete('aggregator_category')->execute(); @@ -681,7 +721,7 @@ class ImportOPMLTestCase extends AggregatorTestCase { } /** - * Submit form filled with invalid fields. + * Submits form filled with invalid fields. */ function validateImportFormFields() { $before = db_query('SELECT COUNT(*) FROM {aggregator_feed}')->fetchField(); @@ -707,7 +747,7 @@ class ImportOPMLTestCase extends AggregatorTestCase { } /** - * Submit form with invalid, empty and valid OPML files. + * Submits form with invalid, empty, and valid OPML files. */ function submitImportForm() { $before = db_query('SELECT COUNT(*) FROM {aggregator_feed}')->fetchField(); @@ -766,6 +806,9 @@ class ImportOPMLTestCase extends AggregatorTestCase { $this->assertTrue($category, 'Categories are correct.'); } + /** + * Tests the import of an OPML file. + */ function testOPMLImport() { $this->openImportForm(); $this->validateImportFormFields(); @@ -773,6 +816,9 @@ class ImportOPMLTestCase extends AggregatorTestCase { } } +/** + * Tests functionality of the cron process in the Aggregator module. + */ class AggregatorCronTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -783,7 +829,7 @@ class AggregatorCronTestCase extends AggregatorTestCase { } /** - * Add feeds update them on cron. + * Adds feeds and updates them via cron process. */ public function testCron() { // Create feed and test basic updating on cron. @@ -819,6 +865,9 @@ class AggregatorCronTestCase extends AggregatorTestCase { } } +/** + * Tests rendering functionality in the Aggregator module. + */ class AggregatorRenderingTestCase extends AggregatorTestCase { public static function getInfo() { return array( @@ -829,9 +878,9 @@ class AggregatorRenderingTestCase extends AggregatorTestCase { } /** - * Add a feed block to the page and checks its links. + * Adds a feed block to the page and checks its links. * - * TODO: Test the category block as well. + * @todo Test the category block as well. */ public function testBlockLinks() { // Create feed. @@ -890,7 +939,7 @@ class AggregatorRenderingTestCase extends AggregatorTestCase { } /** - * Create a feed and check that feed's page. + * Creates a feed and checks that feed's page. */ public function testFeedPage() { // Increase the number of items published in the rss.xml feed so we have @@ -913,7 +962,7 @@ class AggregatorRenderingTestCase extends AggregatorTestCase { } /** - * Tests for feed parsing. + * Tests feed parsing in the Aggregator module. */ class FeedParserTestCase extends AggregatorTestCase { public static function getInfo() { @@ -933,7 +982,7 @@ class FeedParserTestCase extends AggregatorTestCase { } /** - * Test a feed that uses the RSS 0.91 format. + * Tests a feed that uses the RSS 0.91 format. */ function testRSS091Sample() { $feed = $this->createFeed($this->getRSS091Sample()); @@ -955,7 +1004,7 @@ class FeedParserTestCase extends AggregatorTestCase { } /** - * Test a feed that uses the Atom format. + * Tests a feed that uses the Atom format. */ function testAtomSample() { $feed = $this->createFeed($this->getAtomSample());