Skip to content

GitLab

Commit b7a2becd authored by Gábor Hojtsy's avatar Gábor Hojtsy
Browse files

#197314 by vitezslav.smid (as GHOP 39): improve/add/update phpdoc in... 

#197314 by vitezslav.smid (as GHOP 39): improve/add/update phpdoc in aggregator, comment and system modules
parent 97b326ff
Hide whitespace changes
Inline Side-by-side
modules/aggregator/aggregator.admin.inc
View file @ b7a2becd
......@@ -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) {
......
modules/aggregator/aggregator.module
View file @ b7a2becd
......@@ -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');
......
modules/aggregator/aggregator.pages.inc
View file @ b7a2becd
......@@ -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) {
......
modules/comment/comment.admin.inc
View file @ b7a2becd
......@@ -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);
......
modules/comment/comment.install
View file @ b7a2becd
......@@ -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.
......
modules/comment/comment.module
View file @ b7a2becd
......@@ -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