diff -urp ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.admin.inc ./modules/aggregator/aggregator.admin.inc --- ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.admin.inc 2007-12-04 17:34:27.000000000 +0100 +++ ./modules/aggregator/aggregator.admin.inc 2007-12-09 11:26:55.000000000 +0100 @@ -7,12 +7,19 @@ */ /** - * Menu callback; displays the aggregator administration page. + * Menu callback; calls aggregator_view() to display the aggregator administration page. + * + * @see aggregator_view() */ 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'); @@ -42,6 +49,9 @@ function aggregator_view() { /** * Form builder; Generate a form to add/edit feed sources. * + * @param $form_state An associative array containing the current state of the form; not used. + * @param $edit An array of form fields values. + * @return The form structure. * @ingroup forms * @see aggregator_form_feed_validate(). * @see aggregator_form_feed_submit(). @@ -103,6 +113,9 @@ function aggregator_form_feed(&$form_sta /** * Validate aggregator_form_feed form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function aggregator_form_feed_validate($form, &$form_state) { if ($form_state['values']['op'] == t('Save')) { @@ -131,6 +144,8 @@ function aggregator_form_feed_validate($ /** * Process aggregator_form_feed form submissions. * @todo Add delete confirmation dialog. + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function aggregator_form_feed_submit($form, &$form_state) { if ($form_state['values']['op'] == t('Delete')) { @@ -172,6 +187,9 @@ function aggregator_form_feed_submit($fo /** * 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. + * @see aggregator_remove() */ function aggregator_admin_remove_feed($feed) { aggregator_remove($feed); @@ -180,6 +198,9 @@ function aggregator_admin_remove_feed($f /** * Menu callback; refreshes a feed, then redirects to the overview page. + * + * @param $feed An associative array describing the feed to be refreshed. + * @see aggregator_refresh() */ function aggregator_admin_refresh_feed($feed) { aggregator_refresh($feed); @@ -189,6 +210,7 @@ function aggregator_admin_refresh_feed($ /** * Form builder; Configure the aggregator system. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -226,6 +248,9 @@ function aggregator_admin_settings() { /** * Form builder; Generate a form to add/edit/delete aggregator categories. * + * @param $form_state An associative array containing the current state of the form; not used. + * @param $edit An array of form fields values. + * @return The form structure. * @ingroup forms * @see aggregator_form_category_validate(). * @see aggregator_form_category_submit(). @@ -253,6 +278,9 @@ function aggregator_form_category(&$form /** * Validate aggregator_form_feed form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function aggregator_form_category_validate($form, &$form_state) { if ($form_state['values']['op'] == t('Save')) { @@ -272,6 +300,8 @@ function aggregator_form_category_valida /** * Process aggregator_form_category form submissions. * @todo Add delete confirmation dialog. + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function aggregator_form_category_submit($form, &$form_state) { if ($form_state['values']['op'] == t('Delete')) { diff -urp ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.install ./modules/aggregator/aggregator.install --- ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.install 2007-11-04 15:33:06.000000000 +0100 +++ ./modules/aggregator/aggregator.install 2007-12-09 11:09:45.000000000 +0100 @@ -3,6 +3,8 @@ /** * Implementation of hook_install(). + * + * @see hook_install() */ function aggregator_install() { // Create tables. @@ -11,6 +13,8 @@ function aggregator_install() { /** * Implementation of hook_uninstall(). + * + * @see hook_uninstall() */ function aggregator_uninstall() { // Remove tables. @@ -24,6 +28,8 @@ function aggregator_uninstall() { /** * Implementation of hook_schema(). + * + * @see hook_schema() */ function aggregator_schema() { $schema['aggregator_category'] = array( diff -urp ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.module ./modules/aggregator/aggregator.module --- ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.module 2007-12-04 17:34:27.000000000 +0100 +++ ./modules/aggregator/aggregator.module 2007-12-09 12:03:13.000000000 +0100 @@ -8,6 +8,8 @@ /** * Implementation of hook_help(). + * + * @see hook_help() */ function aggregator_help($path, $arg) { switch ($path) { @@ -29,6 +31,8 @@ function aggregator_help($path, $arg) { /** * Implementation of hook_theme() + * + * @see hook_theme() */ function aggregator_theme() { return array( @@ -77,6 +81,8 @@ function aggregator_theme() { /** * Implementation of hook_menu(). + * + * @see hook_menu() */ function aggregator_menu() { $items['admin/content/aggregator'] = array( @@ -246,22 +252,35 @@ function aggregator_menu() { return $items; } +/** + * Menu callback. + * + * @return An aggregator category title. + */ function _aggregator_category_title($category) { return $category['title']; } +/** + * Init callback. + */ 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(). + * + * @see hook_perm() */ function aggregator_perm() { return array('administer news feeds', 'access news feeds'); @@ -271,6 +290,8 @@ function aggregator_perm() { * Implementation of hook_cron(). * * Checks news feeds for updates once their refresh interval has elapsed. + * + * @see hook_cron() */ function aggregator_cron() { $result = db_query('SELECT * FROM {aggregator_feed} WHERE checked + refresh < %d', time()); @@ -283,6 +304,8 @@ function aggregator_cron() { * Implementation of hook_block(). * * Generates blocks for the latest news items in each category and feed. + * + * @see hook_block() */ function aggregator_block($op = 'list', $delta = 0, $edit = array()) { if (user_access('access news feeds')) { @@ -353,6 +376,8 @@ function aggregator_block($op = 'list', /** * 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 +406,8 @@ 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 +446,11 @@ 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)) { @@ -434,6 +466,10 @@ function aggregator_remove($feed) { /** * Call-back function used by the XML parser. + * + * @param $parser The XML parser. + * @param $name The element name. + * @param $attributes The element's attributes. */ function aggregator_element_start($parser, $name, $attributes) { global $item, $element, $tag, $items, $channel; @@ -478,6 +514,9 @@ function aggregator_element_start($parse /** * Call-back function used by the XML parser. + * + * @param $parser The XML parser. + * @param $name The element name. */ function aggregator_element_end($parser, $name) { global $element; @@ -500,6 +539,9 @@ function aggregator_element_end($parser, /** * Call-back function used by the XML parser. + * + * @param $parser The XML parser. + * @param $data The element data (node value). */ function aggregator_element_data($parser, $data) { global $channel, $element, $items, $item, $image, $tag; @@ -547,6 +589,8 @@ function aggregator_element_data($parser /** * 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; @@ -635,7 +679,7 @@ function aggregator_refresh($feed) { * 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. + * @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)) { @@ -664,7 +708,13 @@ function aggregator_parse_w3cdtf($date_s return FALSE; } } - +/** + * 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 +856,12 @@ function aggregator_parse_feed(&$data, $ 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 +881,12 @@ 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 +895,12 @@ 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 +912,9 @@ 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 +935,9 @@ function theme_aggregator_block_item($it /** * 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', '

      • '), -1, PREG_SPLIT_NO_EMPTY)); @@ -871,6 +945,9 @@ 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 -urp ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.pages.inc ./modules/aggregator/aggregator.pages.inc --- ../drupal-6.0-beta4-vanilla/modules/aggregator/aggregator.pages.inc 2007-10-16 15:48:11.000000000 +0200 +++ ./modules/aggregator/aggregator.pages.inc 2007-12-09 16:19:46.000000000 +0100 @@ -8,6 +8,9 @@ /** * Menu callback; displays the most recent items gathered from any feed. + * + * @return The items HTML. + * @see _aggregator_page_list() */ function aggregator_page_last() { drupal_add_feed(url('aggregator/rss'), variable_get('site_name', 'Drupal') .' '. t('aggregator')); @@ -18,7 +21,12 @@ function aggregator_page_last() { } /** - * Menu callback; displays all the items captured from a particular feed. + * 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. + * @see _aggregator_page_list() */ function aggregator_page_source($arg1, $arg2 = NULL) { // If there are two arguments then this function is the categorize form, and @@ -36,7 +44,11 @@ function aggregator_page_source($arg1, $ } /** - * Menu callback; displays all the items aggregated in a particular category. + * 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')))); @@ -55,6 +67,9 @@ function aggregator_page_category($arg1, /** * 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(); @@ -75,6 +90,11 @@ 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. + * + * @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,7 +115,10 @@ function _aggregator_page_list($items, $ /** * Form builder; build the page list form. * - * @ingroup forms + * @param $items An array of the feed items. + * @param $feed_source The feed source URL. + * @return The form structure. + * @ingroup forms Content to be prepended to the items HTML. * @see aggregator_categorize_items_validate(). * @see aggregator_categorize_items_submit(). */ @@ -135,12 +158,23 @@ function aggregator_categorize_items($it return $form; } +/** + * Validate aggregator_categorize_items form submissions. + * + * @param $form_id Not used. + * @param $form An associative array containing the structure of the form. + */ 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. + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ 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 +190,8 @@ function aggregator_categorize_items_sub /** * 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 +216,7 @@ function theme_aggregator_categorize_ite /** * Process variables for aggregator-wrapper.tpl.php. * - * The $variables array contains the following arguments: - * - $content - * + * @params $variables An associative array of the template variables. * @see aggregator-wrapper.tpl.php */ function template_preprocess_aggregator_wrapper(&$variables) { @@ -192,9 +226,7 @@ function template_preprocess_aggregator_ /** * Process variables for aggregator-item.tpl.php. * - * The $variables array contains the following arguments: - * - $item - * + * @params $variables An associative array of the template variables. * @see aggregator-item.tpl.php */ function template_preprocess_aggregator_item(&$variables) { @@ -225,6 +257,8 @@ function template_preprocess_aggregator_ /** * Menu callback; displays all the feeds used by the aggregator. + * + * @return The output HTML. */ 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'); @@ -249,6 +283,8 @@ function aggregator_page_sources() { /** * Menu callback; displays all the categories used by the aggregator. + * + * @return The output HTML. */ 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'); @@ -271,6 +307,8 @@ function aggregator_page_categories() { /** * Menu callback; generate an RSS 0.92 feed of aggregator items or categories. + * + * @return The output XML. */ function aggregator_page_rss() { $result = NULL; @@ -294,8 +332,10 @@ 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) { @@ -340,6 +380,9 @@ function theme_aggregator_page_rss($feed /** * 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) { @@ -359,6 +402,7 @@ function aggregator_page_opml($cid = NUL /** * Theme the opml feed output. * + * @param $feeds An array of the feeds to theme. * @ingroup themeable */ function theme_aggregator_page_opml($feeds) { @@ -385,10 +429,7 @@ function theme_aggregator_page_opml($fee /** * Process variables for aggregator-summary-items.tpl.php. * - * The $variables array contains the following arguments: - * - $summary_items - * - $source - * + * @params $variables An associative array of the template variables. * @see aggregator-summary-item.tpl.php */ function template_preprocess_aggregator_summary_items(&$variables) { @@ -400,9 +441,7 @@ function template_preprocess_aggregator_ /** * Process variables for aggregator-summary-item.tpl.php. * - * The $variables array contains the following arguments: - * - $item - * + * @params $variables An associative array of the template variables. * @see aggregator-summary-item.tpl.php */ function template_preprocess_aggregator_summary_item(&$variables) { @@ -423,9 +462,7 @@ function template_preprocess_aggregator_ /** * Process variables for aggregator-feed-source.tpl.php. * - * The $variables array contains the following arguments: - * - $feed - * + * @params $variables An associative array of the template variables. * @see aggregator-feed-source.tpl.php */ function template_preprocess_aggregator_feed_source(&$variables) { diff -urp ../drupal-6.0-beta4-vanilla/modules/comment/comment.admin.inc ./modules/comment/comment.admin.inc --- ../drupal-6.0-beta4-vanilla/modules/comment/comment.admin.inc 2007-10-31 18:50:47.000000000 +0100 +++ ./modules/comment/comment.admin.inc 2007-12-09 17:53:02.000000000 +0100 @@ -23,6 +23,9 @@ 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,7 +73,12 @@ function comment_admin_overview($type = } /** + * Validate comment_admin_overview form submissions. + * * We can't execute any 'Update options' if no comments were selected. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function comment_admin_overview_validate($form, &$form_state) { $form_state['values']['comments'] = array_diff($form_state['values']['comments'], array(0)); @@ -81,8 +89,13 @@ function comment_admin_overview_validate } /** + * Process comment_admin_overview form submissions. + * * Execute the chosen 'Update option' on the selected comments, such as * publishing, unpublishing or deleting. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function comment_admin_overview_submit($form, &$form_state) { $operations = comment_operations(); @@ -110,6 +123,8 @@ function comment_admin_overview_submit($ /** * Theme the comment admin form. * + * @param $form An associative array containing the structure of the form. + * @return The output HTML. * @ingroup themeable */ function theme_comment_admin_overview($form) { @@ -144,6 +159,8 @@ function theme_comment_admin_overview($f * 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,7 +193,13 @@ function comment_multiple_delete_confirm } /** + * Process comment_multiple_delete_confirm form submissions. + * * Perform the actual comment deletion. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + * @return Where to redirect afterwards. */ function comment_multiple_delete_confirm_submit($form, &$form_state) { if ($form_state['values']['confirm']) { @@ -193,6 +216,9 @@ function comment_multiple_delete_confirm /** * Menu callback; delete a comment. + * + * @param $cid The comment do be deleted. + * @return A confirmation form HTML. */ 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)); @@ -213,6 +239,9 @@ function comment_delete($cid = NULL) { /** * Form builder; Builds the confirmation form for deleting a single comment. * + * @param $form_state An associative array containing the current state of the form; not used. + * @param $comment An associative array describing the comment to be deleted. + * @return The form structure. * @ingroup forms * @see comment_confirm_delete_submit(). */ @@ -229,6 +258,13 @@ function comment_confirm_delete(&$form_s 'comment_confirm_delete'); } +/** + * Process comment_confirm_delete form submissions. + * + * @param $form An associative array containing the structure of the form. + * @param $form_state An associative array containing the current state of the form. + * @return Where to redirect afterwards. + */ function comment_confirm_delete_submit($form, &$form_state) { drupal_set_message(t('The comment and all its replies have been deleted.')); @@ -246,6 +282,11 @@ function comment_confirm_delete_submit($ 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); diff -urp ../drupal-6.0-beta4-vanilla/modules/comment/comment.install ./modules/comment/comment.install --- ../drupal-6.0-beta4-vanilla/modules/comment/comment.install 2007-11-26 20:55:15.000000000 +0100 +++ ./modules/comment/comment.install 2007-12-09 21:14:17.000000000 +0100 @@ -3,6 +3,8 @@ /** * Implementation of hook_enable(). + * + * @see hook_enable() */ function comment_enable() { // Insert records into the node_comment_statistics for nodes that are missing. @@ -58,6 +60,8 @@ function comment_update_6002() { /** * Implementation of hook_schema(). + * + * @see hook_schema() */ function comment_schema() { $schema['comments'] = array( @@ -201,4 +205,3 @@ function comment_schema() { return $schema; } - diff -urp ../drupal-6.0-beta4-vanilla/modules/comment/comment.module ./modules/comment/comment.module --- ../drupal-6.0-beta4-vanilla/modules/comment/comment.module 2007-11-29 12:54:37.000000000 +0100 +++ ./modules/comment/comment.module 2007-12-09 21:55:45.000000000 +0100 @@ -122,6 +122,8 @@ define('COMMENT_PREVIEW_REQUIRED', 1); /** * Implementation of hook_help(). + * + * @see hook_help() */ function comment_help($path, $arg) { switch ($path) { @@ -139,6 +141,8 @@ function comment_help($path, $arg) { /** * Implementation of hook_theme() + * + * @see hook_theme() */ function comment_theme() { return array( @@ -192,6 +196,8 @@ function comment_theme() { /** * Implementation of hook_menu(). + * + * @see hook_menu() */ function comment_menu() { $items['admin/content/comment'] = array( @@ -246,6 +252,7 @@ function comment_menu() { /** * Implementation of hook_node_type(). * + * @see hook_node_type() */ function comment_node_type($op, $info) { $settings = array( @@ -270,6 +277,8 @@ function comment_node_type($op, $info) { /** * Implementation of hook_perm(). + * + * @see hook_perm() */ function comment_perm() { return array('access comments', 'post comments', 'administer comments', 'post comments without approval'); @@ -279,6 +288,8 @@ function comment_perm() { * Implementation of hook_block(). * * Generates a block with the most recent comments. + * + * @see hook_block() */ function comment_block($op = 'list', $delta = 0) { if ($op == 'list') { @@ -331,6 +342,11 @@ 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 +389,9 @@ function comment_new_page_count($num_com } /** - * 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() { @@ -390,6 +406,8 @@ function theme_comment_block() { /** * Implementation of hook_link(). + * + * @see hook_link() */ function comment_link($type, $node = NULL, $teaser = FALSE) { $links = array(); @@ -471,6 +489,11 @@ function comment_link($type, $node = NUL return $links; } +/** + * Implementation of hook_form_alter(). + * + * @see 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( @@ -576,6 +599,7 @@ function comment_form_alter(&$form, $for /** * Implementation of hook_nodeapi(). * + * @see hook_nodeapi() */ function comment_nodeapi(&$node, $op, $arg = 0) { switch ($op) { @@ -622,6 +646,8 @@ function comment_nodeapi(&$node, $op, $a /** * Implementation of hook_user(). + * + * @see hook_user() */ function comment_user($type, $edit, &$user, $category = NULL) { if ($type == 'delete') { @@ -637,6 +663,10 @@ function comment_user($type, $edit, &$us * 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 +676,11 @@ 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 +802,13 @@ 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 The comment to which the links will be related. + * @param $return Not used. + * @return An associative array containing the links. + */ function comment_links($comment, $return = 1) { global $user; @@ -1025,6 +1067,9 @@ function comment_render($node, $cid = 0) /** * Comment operations. We offer different update operations depending on * which comment administration page we're on. + * + * @param $action The comment administration page. + * @return An associative array containing the offered operations. */ function comment_operations($action = NULL) { if ($action == 'publish') { @@ -1055,11 +1100,20 @@ function comment_operations($action = NU /** * Load the entire comment by cid. + * + * @param $cid The identifying comment id. + * @return The comment object. */ function _comment_load($cid) { return db_fetch_object(db_query('SELECT * FROM {comments} WHERE cid = %d', $cid)); } +/** + * Get comment count for a node. + * + * @param $nid The node id. + * @return The comment count. + */ function comment_num_all($nid) { static $cache; @@ -1069,6 +1123,12 @@ function comment_num_all($nid) { return $cache[$nid]; } +/** + * Get replies count for a comment. + * + * @param $pid The comment id. + * @return The replies count. + */ function comment_num_replies($pid) { static $cache; @@ -1080,7 +1140,7 @@ function comment_num_replies($pid) { } /** - * get number of new comments for current user and specified node + * Get number of new comments for current user and specified node * * @param $nid node-id to count comments for * @param $timestamp time to count from (defaults to time of last user access @@ -1108,6 +1168,12 @@ function comment_num_new($nid, $timestam } +/** + * Validate comment data. + * + * @param $edit An associative array containig the comment data. + * @return The original $edit. + */ function comment_validate($edit) { global $user; @@ -1163,10 +1229,13 @@ function comment_validate($edit) { /** * Generate the basic commenting form, for appending to a node or display on a separate page. * + * @param $form_state An associative array containing the current state of the form; not used. + * @param $edit An array of form fields values. + * @param $title Not used. + * @return The form structure. * @ingroup forms * @see comment_form_validate(). * @see comment_form_submit(). - * */ function comment_form(&$form_state, $edit, $title = NULL) { global $user; @@ -1318,7 +1387,7 @@ function comment_form(&$form_state, $edi if (!form_get_errors() && ((variable_get('comment_preview_'. $node->type, COMMENT_PREVIEW_REQUIRED) == COMMENT_PREVIEW_OPTIONAL) || ($op == t('Preview')) || ($op == t('Save')))) { $form['submit'] = array('#type' => 'submit', '#value' => t('Save'), '#weight' => 19); } - + $form['preview'] = array('#type' => 'button', '#value' => t('Preview'), '#weight' => 20); $form['#token'] = 'comment'. $edit['nid'] . (isset($edit['pid']) ? $edit['pid'] : ''); @@ -1333,10 +1402,25 @@ function comment_form(&$form_state, $edi return $form; } +/** + * Theme the comment form box. + * + * @param $edit The form structure. + * @param $title The form title. + * @return The output HTML. + */ function comment_form_box($edit, $title = NULL) { return theme('box', $title, drupal_get_form('comment_form', $edit, $title)); } +/** + * Form builder; Generate and validate a comment preview form. + * + * @param $form An array of form fields values. + * @param $form_state An associative array containing the current state of the form. + * @return The form structure. + * @ingroup forms + */ function comment_form_add_preview($form, &$form_state) { global $user; $edit = $form_state['values']; @@ -1397,6 +1481,13 @@ function comment_form_add_preview($form, return $form; } + +/** + * Validate comment form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function comment_form_validate($form, &$form_state) { global $user; if ($user->uid === 0) { @@ -1410,6 +1501,11 @@ function comment_form_validate($form, &$ comment_validate($form_state['values']); } +/** + * Prepare a comment for submission. + * + * @param $comment_values An associative array containing the comment data. + */ function _comment_form_submit(&$comment_values) { $comment_values += array('subject' => ''); if (!isset($comment_values['date'])) { @@ -1438,6 +1534,12 @@ function _comment_form_submit(&$comment_ } } +/** + * Process comment form submissions; prepare the comment, store it, and set a redirection target. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function comment_form_submit($form, &$form_state) { _comment_form_submit($form_state['values']); if ($cid = comment_save($form_state['values'])) { @@ -1448,7 +1550,16 @@ function comment_form_submit($form, &$fo } } -function theme_comment_view($comment, $node, $links = array(), $visible = 1) { +/** + * Theme a single comment block. + * + * @param $comment The comment object. + * @param $node The comment node. + * @param $links An associative array containing control links. + * @param $visible Switches between folded/unfolded view. + * @return The output HTML. + */ +function theme_comment_view($comment, $node, $links = array(), $visible = TRUE) { static $first_new = TRUE; $output = ''; @@ -1478,6 +1589,15 @@ function theme_comment_view($comment, $n return $output; } + +/** + * Build a comment control form. + * + * @param $mode Comment display mode. + * @param $order Comment order mode. + * @param $comments_per_page Comments per page. + * @return The form structure. + */ function comment_controls($mode = COMMENT_MODE_THREADED_EXPANDED, $order = COMMENT_ORDER_NEWEST_FIRST, $comments_per_page = 50) { $form['mode'] = array('#type' => 'select', '#default_value' => $mode, @@ -1507,6 +1627,12 @@ function comment_controls($mode = COMMEN return $form; } +/** + * Theme the comment controls form. + * + * @param $form The form structure. + * @return The output HTML. + */ function theme_comment_controls($form) { $output = '
        '; $output .= drupal_render($form); @@ -1515,6 +1641,11 @@ function theme_comment_controls($form) { return theme('box', t('Comment viewing options'), $output); } +/** + * Process comment_controls form submissions. + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function comment_controls_submit($form, &$form_state) { global $user; @@ -1535,11 +1666,7 @@ function comment_controls_submit($form, /** * Process variables for comment.tpl.php. * - * The $variables array contains the following arguments: - * - $comment - * - $node - * - $links - * + * @params $variables An associative array of the template variables. * @see comment.tpl.php * @see theme_comment() */ @@ -1561,9 +1688,7 @@ function template_preprocess_comment(&$v /** * Process variables for comment-folded.tpl.php. * - * The $variables array contains the following arguments: - * - $comment - * + * @params $variables An associative array of the template variables. * @see comment-folded.tpl.php * @see theme_comment_folded() */ @@ -1575,22 +1700,56 @@ function template_preprocess_comment_fol $variables['title'] = l($comment->subject, comment_node_url() .'/'. $comment->cid, array('fragment' => "comment-$comment->cid")); } +/** + * Theme comment flat collapsed view. + * + * @param $comment The comment to be themed. + * @param $node The comment node. + * @return The output HTML. + */ function theme_comment_flat_collapsed($comment, $node) { return theme('comment_view', $comment, $node, '', 0); } +/** + * Theme comment flat expanded view. + * + * @param $comment The comment to be themed. + * @param $node The comment node. + * @return The output HTML. + */ function theme_comment_flat_expanded($comment, $node) { return theme('comment_view', $comment, $node, module_invoke_all('link', 'comment', $comment, 0)); } +/** + * Theme comment thread collapsed view. + * + * @param $comment The comment to be themed. + * @param $node The comment node. + * @return The output HTML. + */ function theme_comment_thread_collapsed($comment, $node) { return theme('comment_view', $comment, $node, '', 0); } +/** + * Theme comment thread expanded view. + * + * @param $comment The comment to be themed. + * @param $node The comment node. + * @return The output HTML. + */ function theme_comment_thread_expanded($comment, $node) { return theme('comment_view', $comment, $node, module_invoke_all('link', 'comment', $comment, 0)); } +/** + * Theme a "you can't post comments" notice. + * + * @param $node The comment node. + * @return The output HTML. + */ function theme_comment_post_forbidden($node) { global $user; if ($user->uid) { @@ -1617,10 +1776,7 @@ function theme_comment_post_forbidden($n /** * Process variables for comment-wrapper.tpl.php. * - * The $variables array contains the following arguments: - * - $content - * - $node - * + * @params $variables An associative array of the template variables. * @see comment-wrapper.tpl.php * @see theme_comment_wrapper() */ @@ -1633,7 +1789,10 @@ function template_preprocess_comment_wra } /** - * Make the submitted variable themable + * Theme a "Submitted by ..." notice. + * + * @param $comment The comment. + * @return The output HTML. */ function theme_comment_submitted($comment) { return t('Submitted by !username on @datetime.', @@ -1682,7 +1841,8 @@ function _comment_per_page() { /** * Return a current comment display setting * - * $setting can be one of these: 'mode', 'sort', 'comments_per_page' + * @param $setting can be one of these: 'mode', 'sort', 'comments_per_page' + * @param $node The comment node in question. */ function _comment_get_display_setting($setting, $node) { global $user; @@ -1802,6 +1962,8 @@ function vancode2int($c = '00') { /** * Implementation of hook_hook_info(). + * + * @see hook_hook_info() */ function comment_hook_info() { return array( @@ -1826,6 +1988,8 @@ function comment_hook_info() { /** * Implementation of hook_action_info(). + * + * @see hook_action_info() */ function comment_action_info() { return array( @@ -1869,6 +2033,12 @@ function comment_unpublish_action($comme watchdog('action', 'Unpublished comment %subject.', array('%subject' => $subject)); } +/** + * Form builder; Prepare a form for blacklisted keywords. + * + * @param $context An array of form fields values. + * @return The form structure. + */ function comment_unpublish_by_keyword_action_form($context) { $form['keywords'] = array( '#title' => t('Keywords'), @@ -1879,6 +2049,12 @@ function comment_unpublish_by_keyword_ac return $form; } +/** + * Process comment_unpublish_by_keyword_action_form form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function comment_unpublish_by_keyword_action_submit($form, $form_state) { return array('keywords' => drupal_explode_tags($form_state['values']['keywords'])); } diff -urp ../drupal-6.0-beta4-vanilla/modules/comment/comment.pages.inc ./modules/comment/comment.pages.inc --- ../drupal-6.0-beta4-vanilla/modules/comment/comment.pages.inc 2007-10-31 18:50:47.000000000 +0100 +++ ./modules/comment/comment.pages.inc 2007-12-09 22:13:18.000000000 +0100 @@ -6,6 +6,12 @@ * User page callbacks for the comment module. */ +/** + * Form builder; generate a comment editing form. + * + * @param $cid ID of the comment to be edited. + * @return The output HTML. + */ function comment_edit($cid) { global $user; diff -urp ../drupal-6.0-beta4-vanilla/modules/system/box.tpl.php ./modules/system/box.tpl.php --- ../drupal-6.0-beta4-vanilla/modules/system/box.tpl.php 2007-08-07 10:39:36.000000000 +0200 +++ ./modules/system/box.tpl.php 2007-12-10 07:03:28.000000000 +0100 @@ -1,5 +1,17 @@
        diff -urp ../drupal-6.0-beta4-vanilla/modules/system/system.admin.inc ./modules/system/system.admin.inc --- ../drupal-6.0-beta4-vanilla/modules/system/system.admin.inc 2007-12-05 20:12:59.000000000 +0100 +++ ./modules/system/system.admin.inc 2007-12-10 21:03:06.000000000 +0100 @@ -66,6 +66,8 @@ function system_main_admin_page($arg = N * For example, 'admin/content/types' needs to have a destination to be valid * in the Drupal menu system, but too much information there might be * hidden, so we supply the contents of the block. + * + * @return The output HTML. */ function system_admin_menu_block_page() { $item = menu_get_item(); @@ -77,6 +79,8 @@ function system_admin_menu_block_page() /** * Menu callback; Sets whether the admin menu is in compact mode or not. + * + * @param $mode Valid values are 'on' and 'off'. */ function system_admin_compact_page($mode = 'off') { global $user; @@ -86,6 +90,8 @@ function system_admin_compact_page($mode /** * Menu callback; prints a listing of admin tasks for each installed module. + * + * @return The output HTML. */ function system_admin_by_module() { @@ -120,6 +126,8 @@ function system_admin_by_module() { /** * Menu callback; displays a module's settings page. + * + * @return The output HTML. */ function system_settings_overview() { // Check database setup if necessary @@ -138,6 +146,7 @@ function system_settings_overview() { /** * Form builder; This function allows selection of the theme to show in administration sections. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -171,6 +180,7 @@ function system_admin_theme_settings() { /** * Menu callback; displays a listing of all themes. * + * @return The form structure. * @ingroup forms * @see system_themes_form_submit(). */ @@ -241,6 +251,12 @@ function system_themes_form() { return $form; } +/** + * Process system_themes_form_submit form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function system_themes_form_submit($form, &$form_state) { // Store list of previously enabled themes and disable all themes @@ -296,6 +312,9 @@ function system_themes_form_submit($form /** * Form builder; display theme configuration for entire site and individual themes. * + * @param $form_state An associative array containing the current state of the form. + * @param $key A theme name. + * @return The form structure. * @ingroup forms * @see system_theme_settings_submit(). */ @@ -512,6 +531,12 @@ function system_theme_settings(&$form_st return $form; } +/** + * Process system_theme_settings form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function system_theme_settings_submit($form, &$form_state) { $op = isset($_POST['op']) ? $_POST['op'] : ''; $key = $form_state['values']['var']; @@ -532,7 +557,12 @@ function system_theme_settings_submit($f } /** - * Recursively check compatability + * Recursively check compatibility. + * + * @param $incompatible An associative array which at the end of the check contains all incompatible files as the keys, their values being TRUE. + * @param $files The set of files that will be tested. + * @param $file The file at which the check starts. + * @return Returns TRUE if an incompatible file is found, NULL (no return value) otherwise. */ function _system_is_incompatible(&$incompatible, $files, $file) { if (isset($incompatible[$file->name])) { @@ -559,6 +589,7 @@ function _system_is_incompatible(&$incom * disabled dependencies and also to ensure that the module cannot be disabled if the module has * enabled dependents. * + * @param $form_state An associative array containing the current state of the form. * @ingroup forms * @see theme_system_modules(). * @see system_modules_submit(). @@ -720,12 +751,21 @@ function system_modules($form_state = ar return $form; } + + +/** + * Array sorting callback; sorts modules by their name. + */ function system_sort_modules_by_info_name($a, $b) { return strcasecmp($a->info['name'], $b->info['name']); } /** * Form process callback function to disable check boxes. + * + * @param $form The form structure. + * @param $edit Not used. + * @return The form structure. */ function system_modules_disable($form, $edit) { foreach ($form['#disabled_modules'] as $key) { @@ -743,8 +783,8 @@ function system_modules_disable($form, $ * The contents of $form_state['storage']; an array with two * elements: the list of dependencies and the list of status * form field values from the previous screen. + * @return The form structure. * @ingroup forms - * @see */ function system_modules_confirm_form($modules, $storage) { $form = array(); @@ -787,6 +827,9 @@ function system_modules_confirm_form($mo /** * Submit callback; handles modules form submission. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function system_modules_submit($form, &$form_state) { include_once './includes/install.inc'; @@ -887,6 +930,14 @@ function system_modules_submit($form, &$ return; } + +/** + * Generate a list of dependencies for modules that are going to be switched on. + * + * @param $modules The list of modules to check. + * @param $form_values Submitted form values used to determine what modules have been enabled. + * @return An array of dependencies. + */ function system_module_build_dependencies($modules, $form_values) { static $dependencies; @@ -976,7 +1027,7 @@ function system_modules_uninstall($form_ * * @ingroup forms * @param - * $form_state['values'] Submitted form values. + * $storage An associative array of modules selected to be uninstalled. * @return * A form array representing modules to confirm. */ @@ -1014,10 +1065,8 @@ function system_modules_uninstall_confir /** * Validates the submitted uninstall form. * - * @param - * $form_id The form ID. - * @param - * $form_state['values'] Submitted form values. + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function system_modules_uninstall_validate($form, &$form_state) { // Form submitted, but no modules selected. @@ -1030,10 +1079,8 @@ function system_modules_uninstall_valida /** * Processes the submitted uninstall form. * - * @param - * $form_id The form ID. - * @param - * $form_state['values'] Submitted form values. + * @param $form An associative array containing the structure of the form. + * @param $form_state An associative array containing the current state of the form. */ function system_modules_uninstall_submit($form, &$form_state) { // Make sure the install API is available. @@ -1057,6 +1104,7 @@ function system_modules_uninstall_submit /** * Form builder; The general site information form. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1115,6 +1163,7 @@ function system_site_information_setting /** * Form builder; Configure error reporting settings. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1149,6 +1198,8 @@ function system_error_reporting_settings /** * Menu callback; Menu page for the various logging options. + * + * @return The output HTML. */ function system_logging_overview() { $item = menu_get_item('admin/settings/logging'); @@ -1162,6 +1213,7 @@ function system_logging_overview() { /** * Form builder; Configure site performance settings. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1269,6 +1321,9 @@ function system_performance_settings() { /** * Clear system caches. + * + * @param $form_state Not used. + * @param $form Not used. */ function system_clear_cache_submit(&$form_state, $form) { drupal_flush_all_caches(); @@ -1278,6 +1333,7 @@ function system_clear_cache_submit(&$for /** * Form builder; Configure the site file handling. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1315,6 +1371,7 @@ function system_file_system_settings() { /** * Form builder; Configure site image toolkit usage. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1340,6 +1397,7 @@ function system_image_toolkit_settings() /** * Form builder; Configure how the site handles RSS feeds. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1366,6 +1424,7 @@ function system_rss_feeds_settings() { /** * Form builder; Configure the site date and time settings. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). * @see system_date_time_settings(). @@ -1511,6 +1570,12 @@ function system_date_time_settings() { return $form; } +/** + * Process system_date_time_settings form submissions. + * + * @param $form An associative array containing the structure of the form. + * @param $form_state An associative array containing the current state of the form. + */ function system_date_time_settings_submit($form, &$form_state) { if ($form_state['values']['date_format_short'] == 'custom') { $form_state['values']['date_format_short'] = $form_state['values']['date_format_short_custom']; @@ -1536,6 +1601,7 @@ function system_date_time_lookup() { /** * Form builder; Configure the site's maintenance status. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1562,6 +1628,7 @@ function system_site_maintenance_setting /** * Form builder; Configure Clean URL settings. * + * @return The form structure. * @ingroup forms * @see system_settings_form(). */ @@ -1637,6 +1704,13 @@ function system_php() { exit(); } +/** + * Theme a SQL result table. + * + * @param $data The actual table data. + * @param $keys Data keys and descriptions. + * @return The output HTML. + */ function _system_sql($data, $keys) { $rows = array(); foreach ($keys as $key => $explanation) { @@ -1650,6 +1724,8 @@ function _system_sql($data, $keys) { /** * Menu callback: return information about PHP. + * + * @return The output HTML. */ function system_sql() { @@ -1818,6 +1894,9 @@ function theme_admin_page($blocks) { /** * Theme output of the dashboard page. + * + * @param $menu_items An array of modules to be displayed. + * @return The output HTML. */ function theme_system_admin_by_module($menu_items) { $stripe = 0; @@ -1860,8 +1939,10 @@ function theme_system_admin_by_module($m } /** - * Theme status report + * Theme requirements status report. * + * @param $requirements An array of requirements. + * @return The output HTML. * @ingroup themeable */ function theme_status_report(&$requirements) { @@ -1895,8 +1976,10 @@ function theme_status_report(&$requireme } /** - * Theme call back for the modules form. + * Theme callback for the modules form. * + * @param $form An associative array containing the structure of the form. + * @return The output HTML. * @ingroup themeable */ function theme_system_modules($form) { @@ -2022,7 +2105,8 @@ function theme_system_modules_uninstall( /** * Theme the theme select form. - * + * @param $form An associative array containing the structure of the form. + * @return The output HTML. * @ingroup themeable */ function theme_system_theme_select_form($form) { @@ -2044,6 +2128,8 @@ function theme_system_theme_select_form( /** * Theme function for the system themes form. * + * @param $form An associative array containing the structure of the form. + * @return The output HTML. * @ingroup themeable */ function theme_system_themes_form($form) { diff -urp ../drupal-6.0-beta4-vanilla/modules/system/system.install ./modules/system/system.install --- ../drupal-6.0-beta4-vanilla/modules/system/system.install 2007-12-04 17:39:22.000000000 +0100 +++ ./modules/system/system.install 2007-12-10 21:05:23.000000000 +0100 @@ -3,6 +3,9 @@ /** * Test and report Drupal installation requirements. + * + * @param $phase The current system installation phase. + * @return An array of system requirements. */ function system_requirements($phase) { $requirements = array(); @@ -246,6 +249,8 @@ function system_requirements($phase) { /** * Implementation of hook_install(). + * + * @see hook_install() */ function system_install() { if ($GLOBALS['db_type'] == 'pgsql') { @@ -356,6 +361,8 @@ function system_install() { /** * Implementation of hook_schema(). + * + * @see hook_schema() */ function system_schema() { // NOTE: {variable} needs to be created before all other tables, as diff -urp ../drupal-6.0-beta4-vanilla/modules/system/system.module ./modules/system/system.module --- ../drupal-6.0-beta4-vanilla/modules/system/system.module 2007-12-05 22:18:29.000000000 +0100 +++ ./modules/system/system.module 2007-12-10 22:12:39.000000000 +0100 @@ -6,19 +6,45 @@ * Configuration system that lets administrators modify the workings of the site. */ +/** + * The current system version. + */ define('VERSION', '6.0-beta4'); + +/** + * Core API compatibility. + */ define('DRUPAL_CORE_COMPATIBILITY', '6.x'); -define('DRUPAL_MINIMUM_PHP', '4.3.3'); -define('DRUPAL_MINIMUM_MYSQL', '4.1.0'); // If using MySQL -define('DRUPAL_MINIMUM_PGSQL', '7.4'); // If using PostgreSQL -define('DRUPAL_MINIMUM_APACHE', '1.3'); // If using Apache +/** + * Minimum supported version of PHP. + */ +define('DRUPAL_MINIMUM_PHP', '4.3.3'); + +/** + * Minimum supported version of MySQL, if it is used. + */ +define('DRUPAL_MINIMUM_MYSQL', '4.1.0'); + +/** + * Minimum supported version of PostgreSQL, if it is used. + */ +define('DRUPAL_MINIMUM_PGSQL', '7.4'); + +/** + * Minimum supported version of Apache, if it is used. + */ +define('DRUPAL_MINIMUM_APACHE', '1.3'); -// Maximum age of temporary files in seconds. +/** + * Maximum age of temporary files in seconds. + */ define('DRUPAL_MAXIMUM_TEMP_FILE_AGE', 1440); /** * Implementation of hook_help(). + * + * @see hook_help() */ function system_help($path, $arg) { global $base_url; @@ -76,6 +102,12 @@ function system_help($path, $arg) { } } + +/** + * Implementation of hook_theme(). + * + * @see hook_theme() + */ function system_theme() { return array_merge(drupal_common_theme(), array( 'system_theme_select_form' => array( @@ -121,6 +153,8 @@ function system_theme() { } /** * Implementation of hook_perm(). + * + * @see hook_perm() */ function system_perm() { return array('administer site configuration', 'access administration pages', 'administer actions', 'select different theme', 'administer files'); @@ -128,6 +162,8 @@ function system_perm() { /** * Implementation of hook_elements(). + * + * @see hook_elements() */ function system_elements() { // Top level form @@ -162,6 +198,8 @@ function system_elements() { /** * Implementation of hook_menu(). + * + * @see hook_menu() */ function system_menu() { $items['system/files'] = array( @@ -459,6 +497,12 @@ function system_menu() { return $items; } + +/** + * Implementation of hook_init(). + * + * @see hook_init() + */ function system_init() { // Use the administrative theme if the user is looking at a page in the admin/* path. if (arg(0) == 'admin' || (variable_get('node_admin_theme', '0') && arg(0) == 'node' && (arg(1) == 'add' || arg(2) == 'edit'))) { @@ -477,6 +521,8 @@ function system_init() { * Implementation of hook_user(). * * Allows users to individually set their theme and time zone. + * + * @see hook_user() */ function system_user($type, $edit, &$user, $category = NULL) { if ($type == 'form' && $category == 'account') { @@ -504,7 +550,11 @@ function system_user($type, $edit, &$use } /** + * Implementation of hook_block(). + * * Generate a block with a promotional link to Drupal.org. + * + * @see hook_block() */ function system_block($op = 'list', $delta = 0, $edit = NULL) { switch($op) { @@ -543,6 +593,8 @@ function system_block($op = 'list', $del /** * Provide a single block on the administration overview page. + * + * @param $item The menu item to be displayed. */ function system_admin_menu_block($item) { $content = array(); @@ -573,6 +625,13 @@ function system_admin_menu_block($item) } + +/** + * Process admin theme form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function system_admin_theme_submit($form, &$form_state) { // If we're changing themes, make sure the theme has its blocks initialized. if ($form_state['values']['admin_theme'] && $form_state['values']['admin_theme'] != variable_get('admin_theme', '0')) { @@ -662,6 +721,9 @@ function system_check_directory($form_el /** * Retrieves the current status of an array of files in the system table. + * + * @param $files An array of files to check. + * @param $type The type of the files. */ function system_get_files_database(&$files, $type) { // Extract current files from database. @@ -678,8 +740,13 @@ function system_get_files_database(&$fil } } + +/** + * Prepare defaults for themes. + * + * @return An array of default themes settings. + */ function system_theme_default() { - // Prepare defaults for themes. return array( 'regions' => array( 'left' => 'Left sidebar', @@ -738,10 +805,12 @@ function system_theme_data() { /** * Helper function to scan and collect theme .info data and their engines. + * + * @return An associative array of themes information. */ function _system_theme_data() { static $themes_info = array(); - + if (empty($theme_info)) { // Find themes $themes = drupal_system_listing('\.info$', 'themes'); @@ -819,7 +888,7 @@ function _system_theme_data() { } } } - + $themes_info = $themes; } @@ -828,9 +897,12 @@ function _system_theme_data() { /** * Recursive function to find the top level base theme. Themes can inherit - * templates and function implementations from earlier themes; this function - * finds the top level parent that has no ancestor, or returns NULL if there - * isn't a valid parent. + * templates and function implementations from earlier themes. + * + * @param $themes An array of available themes. + * @param $key The name of the theme whose base we are looking for. + * @param $used_keys A recursion parameter preventing endless loops. + * @return Returns the top level parent that has no ancestor or returns NULL if there isn't a valid parent. */ function system_find_base_theme($themes, $key, $used_keys = array()) { $base_key = $themes[$key]->info['base theme']; @@ -913,7 +985,10 @@ function system_initialize_theme_blocks( } /** - * Add default buttons to a form and set its prefix + * Add default buttons to a form and set its prefix. + * + * @param $form An associative array containing the structure of the form. + * @return The form structure. */ function system_settings_form($form) { $form['buttons']['submit'] = array('#type' => 'submit', '#value' => t('Save configuration') ); @@ -936,6 +1011,8 @@ function system_settings_form($form) { * If you want node type configure style handling of your checkboxes, * add an array_filter value to your form. * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function system_settings_form_submit($form, &$form_state) { $op = isset($form_state['values']['op']) ? $form_state['values']['op'] : ''; @@ -982,6 +1059,8 @@ function _system_sort_requirements($a, $ * Implementation of hook_node_type(). * * Updates theme settings after a node type change. + * + * @see hook_node_type() */ function system_node_type($op, $info) { if ($op == 'update' && !empty($info->old_type) && $info->type != $info->old_type) { @@ -1064,6 +1143,14 @@ function system_admin_compact_mode() { return (isset($user->admin_compact_mode)) ? $user->admin_compact_mode : variable_get('admin_compact_mode', FALSE); } + + +/** + * Generate a list of tasks offered by a specified module. + * + * @param $module Module name. + * @return An array of task links. + */ function system_get_module_admin_tasks($module) { static $items; @@ -1105,6 +1192,8 @@ function system_get_module_admin_tasks($ * Implementation of hook_cron(). * * Remove older rows from flood and batch table. Remove old temporary files. + * + * @see hook_cron() */ function system_cron() { // Cleanup the flood. @@ -1129,6 +1218,8 @@ function system_cron() { /** * Implementation of hook_hook_info(). + * + * @see hook_hook_info() */ function system_hook_info() { return array( @@ -1144,6 +1235,8 @@ function system_hook_info() { /** * Implementation of hook_action_info(). + * + * @see hook_action_info() */ function system_action_info() { return array( @@ -1184,6 +1277,8 @@ function system_action_info() { /** * Menu callback. Display an overview of available and configured actions. + * + * @return The HTML output. */ function system_actions_manage() { $output = ''; @@ -1239,6 +1334,8 @@ function system_actions_manage() { /** * Define the form for the actions overview page. * + * @param + * $form_state An associative array containing the current state of the form; not used. * @param $options * An array of configurable actions. * @return @@ -1264,6 +1361,12 @@ function system_actions_manage_form($for return $form; } +/** + * Process system_actions_manage form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function system_actions_manage_form_submit($form, &$form_state) { if ($form_state['values']['action']) { $form_state['redirect'] = 'admin/settings/actions/configure/'. $form_state['values']['action']; @@ -1354,6 +1457,12 @@ function system_actions_configure($form_ return $form; } +/** + * Validate system_actions_configure form submissions. + * + * @param $form An associative array containing the structure of the form. + * @param $form_state An associative array containing the current state of the form. + */ function system_actions_configure_validate($form, $form_state) { $function = actions_function_lookup($form_state['values']['actions_action']) .'_validate'; // Hand off validation to the action. @@ -1362,6 +1471,13 @@ function system_actions_configure_valida } } + +/** + * Process system_actions_configure form submissions. + * + * @param $form An associative array containing the structure of the form. + * @param $form_state An associative array containing the current state of the form. + */ function system_actions_configure_submit($form, &$form_state) { $function = actions_function_lookup($form_state['values']['actions_action']); $submit_function = $function .'_submit'; @@ -1379,8 +1495,8 @@ function system_actions_configure_submit /** * Create the form for confirmation of deleting an action. * - * @param $aid - * The action ID. + * @param $form_state An associative array containing the current state of the form; not used. + * @param $action The action. */ function system_actions_delete_form($form_state, $action) { @@ -1397,7 +1513,12 @@ function system_actions_delete_form($for } /** + * Process system_actions_delete form submissions. + * * Post-deletion operations for action deletion. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. */ function system_actions_delete_form_submit($form, &$form_state) { $aid = $form_state['values']['aid']; @@ -1410,6 +1531,8 @@ function system_actions_delete_form_subm } /** * Post-deletion operations for deleting action orphans. + * + * @param $orphaned An array of orphaned actions. */ function system_action_delete_orphans_post($orphaned) { foreach ($orphaned as $callback) { @@ -1419,7 +1542,6 @@ function system_action_delete_orphans_po /** * Remove actions that are in the database but not supported by any enabled module. - * */ function system_actions_remove_orphans() { actions_synchronize(actions_list(), TRUE); @@ -1471,6 +1593,13 @@ function system_send_email_action_form($ return $form; } + +/** + * Validate system_send_email_action form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function system_send_email_action_validate($form, $form_state) { $form_values = $form_state['values']; // Validate the configuration form. @@ -1480,6 +1609,12 @@ function system_send_email_action_valida } } +/** + * Process system_send_email_action form submissions. + * + * @param $form An associative array containing the structure of the form; not used. + * @param $form_state An associative array containing the current state of the form. + */ function system_send_email_action_submit($form, $form_state) { $form_values = $form_state['values']; // Process the HTML form to store configuration. The keyed array that @@ -1559,6 +1694,8 @@ function system_send_email_action($objec /** * Implementation of hook_mail(). + * + * @see hook_mail() */ function system_mail($key, &$message, $params) { $account = $params['account']; @@ -1695,6 +1832,10 @@ function system_goto_action($object, $co drupal_goto($context['url']); } + +/** + * Generate an array of time zones and their local time&date. + */ function _system_zonelist() { $timestamp = time(); $zonelist = array(-11, -10, -9.5, -9, -8, -7, -6, -5, -4, -3.5, -3, -2, -1, 0, 1, 2, 3, 3.5, 4, 5, 5.5, 5.75, 6, 6.5, 7, 8, 9, 9.5, 10, 10.5, 11, 11.5, 12, 12.75, 13, 14); @@ -1706,6 +1847,9 @@ function _system_zonelist() { return $zones; } +/** + * Create a 'Powered by Drupal' notice. + */ function theme_system_powered_by($image_path) { $image = theme('image', $image_path, t('Powered by Drupal, an open source content management system'), t('Powered by Drupal, an open source content management system')); return l($image, 'http://drupal.org', array('html' => TRUE, 'absolute' => TRUE, 'external' => TRUE));