diff options
| -rw-r--r-- | cron.php | 2 | ||||
| -rw-r--r-- | database/updates.inc | 2 | ||||
| -rw-r--r-- | includes/bootstrap.inc | 12 | ||||
| -rw-r--r-- | includes/common.inc | 268 | ||||
| -rw-r--r-- | includes/database.inc | 3 | ||||
| -rw-r--r-- | includes/database.mysql.inc | 4 | ||||
| -rw-r--r-- | includes/database.pgsql.inc | 6 | ||||
| -rw-r--r-- | includes/file.inc | 2 | ||||
| -rw-r--r-- | includes/menu.inc | 34 | ||||
| -rw-r--r-- | includes/module.inc | 6 | ||||
| -rw-r--r-- | includes/pager.inc | 34 | ||||
| -rw-r--r-- | includes/tablesort.inc | 3 | ||||
| -rw-r--r-- | includes/theme.inc | 5 | ||||
| -rw-r--r-- | modules/aggregator.module | 27 | ||||
| -rw-r--r-- | modules/aggregator/aggregator.module | 27 | ||||
| -rw-r--r-- | modules/filter.module | 28 | ||||
| -rw-r--r-- | modules/filter/filter.module | 28 | ||||
| -rw-r--r-- | modules/forum.module | 29 | ||||
| -rw-r--r-- | modules/forum/forum.module | 29 | ||||
| -rw-r--r-- | modules/node.module | 27 | ||||
| -rw-r--r-- | modules/node/node.module | 27 | ||||
| -rw-r--r-- | modules/search.module | 2 | ||||
| -rw-r--r-- | modules/search/search.module | 2 |
23 files changed, 283 insertions, 324 deletions
@@ -3,7 +3,7 @@ /** * @file - * Handles incoming requests to fire of regularly-scheduled tasks (cron jobs). + * Handles incoming requests to fire off regularly-scheduled tasks (cron jobs). */ include_once 'includes/bootstrap.inc'; diff --git a/database/updates.inc b/database/updates.inc index 4466dc9ba..25dd9eea8 100644 --- a/database/updates.inc +++ b/database/updates.inc @@ -1303,7 +1303,7 @@ function update_98() { /** * Works for both PostgreSQL and MySQL */ - $result = db_query("SELECT pid, src FROM {url_alias} WHERE src LIKE 'taxonomy/%%'", $from); + $result = db_query("SELECT pid, src FROM {url_alias} WHERE src LIKE 'taxonomy/%%'"); while ($alias = db_fetch_object($result)) { list(, $page, $op, $terms) = explode('/', $alias->src); if ($page == 'feed' || $page == 'page') { diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc index e92547109..291eb5bbd 100644 --- a/includes/bootstrap.inc +++ b/includes/bootstrap.inc @@ -1,5 +1,5 @@ <?php -/* $Id$ */ +// $Id$ /** * @file @@ -394,13 +394,6 @@ function watchdog($type, $message, $link = NULL) { } /** - * @name Page messages - * - * Functions to get and set the message of the current page. - * @{ - */ - -/** * Set a message for the user to see. * * The message is stored in the session so that it can persist through a redirect. @@ -436,8 +429,6 @@ function drupal_get_messages() { return $messages; } -/* @} */ - unset($conf); $config = conf_init(); @@ -448,4 +439,5 @@ include_once 'includes/module.inc'; // Initialize configuration variables, using values from conf.php if available. $conf = variable_init(isset($conf) ? $conf : array()); + ?> diff --git a/includes/common.inc b/includes/common.inc index 72324c5f0..b138d79b5 100644 --- a/includes/common.inc +++ b/includes/common.inc @@ -10,10 +10,7 @@ */ /** - * @name Page title - * - * Functions to get and set the title of the current page. - * @{ + * Set the title of the current page, for display on the page and in the title bar. */ function drupal_set_title($title = NULL) { static $stored_title; @@ -24,6 +21,9 @@ function drupal_set_title($title = NULL) { return $stored_title; } +/** + * Get the title of the current page, for display on the page and in the title bar. + */ function drupal_get_title() { $title = drupal_set_title(); @@ -33,18 +33,13 @@ function drupal_get_title() { return $title; } -/* @} */ /** - * @name Page breadcrumbs + * Set the breadcrumb trail for the current page. * - * Functions to get and set the breadcrumb trail of the current page. - * @{ - */ - -/** - * @param $breadcrumb Array of links, starting with "home" and proceeding up - * to but not including the current page. + * @param $breadcrumb + * Array of links, starting with "home" and proceeding up to but not including + * the current page. */ function drupal_set_breadcrumb($breadcrumb = NULL) { static $stored_breadcrumb; @@ -55,6 +50,9 @@ function drupal_set_breadcrumb($breadcrumb = NULL) { return $stored_breadcrumb; } +/** + * Get the breadcrumb trail for the current page. + */ function drupal_get_breadcrumb() { $breadcrumb = drupal_set_breadcrumb(); @@ -64,15 +62,10 @@ function drupal_get_breadcrumb() { return $breadcrumb; } -/* @} */ /** - * @name HTML head contents - * - * Set and get output that should be in the \<head\> tag. - * @{ + * Add output to the head tag of the HTML page. */ - function drupal_set_html_head($data = NULL) { static $stored_head = ''; @@ -82,6 +75,9 @@ function drupal_set_html_head($data = NULL) { return $stored_head; } +/** + * Retrieve output to be displayed in the head tag of the HTML page. + */ function drupal_get_html_head() { global $base_url; @@ -91,14 +87,10 @@ function drupal_get_html_head() { return $output . drupal_set_html_head(); } -/* @} */ /** - * @name URL path alias - * - * Functions to handle path aliases. + * Return an array mapping path aliases to their internal Drupal paths. */ - function drupal_get_path_map($action = '') { static $map = NULL; @@ -107,7 +99,7 @@ function drupal_get_path_map($action = '') { } if (is_null($map)) { - $map = array(); // make $map non-null in case no aliases are defined + $map = array(); // Make $map non-null in case no aliases are defined. $result = db_query('SELECT * FROM {url_alias}'); while ($data = db_fetch_object($result)) { $map[$data->dst] = $data->src; @@ -117,6 +109,9 @@ function drupal_get_path_map($action = '') { return $map; } +/** + * Regenerate the path map from the information in the database. + */ function drupal_rebuild_path_map() { drupal_get_path_map('rebuild'); } @@ -151,17 +146,13 @@ function drupal_get_normal_path($path) { return $path; } } -/* @} */ /** - * @name HTTP headers - * - * Functions to get and set the HTTP headers of the current page. - * @{ + * Set an HTTP response header for the current page. */ function drupal_set_header($header = NULL) { // We use an array to guarantee there are no leading or trailing delimiters. - // This can cause header("") to get called when serving the page later, which + // Otherwise, header('') could get called when serving the page later, which // ends HTTP headers prematurely on some PHP versions. static $stored_headers = array(); @@ -172,16 +163,17 @@ function drupal_set_header($header = NULL) { return implode("\n", $stored_headers); } +/** + * Get the HTTP response headers for the current page. + */ function drupal_get_headers() { return drupal_set_header(); } -/* @} */ /** * @name HTTP handling - * - * Functions to properly handle HTTP responses. * @{ + * Functions to properly handle HTTP responses. */ /** @@ -316,7 +308,7 @@ function drupal_http_request($url, $headers = array(), $method = 'GET', $data = $path .= '?'. $uri['query']; } - // Create http request. + // Create HTTP request. $defaults = array( 'Host' => 'Host: '. $uri['host'], 'User-Agent' => 'User-Agent: Drupal (+http://www.drupal.org/)', @@ -365,7 +357,7 @@ function drupal_http_request($url, $headers = array(), $method = 'GET', $data = 500 => 'Internal Server Error', 501 => 'Not Implemented', 502 => 'Bad Gateway', 503 => 'Service Unavailable', 504 => 'Gateway Time-out', 505 => 'HTTP Version not supported' ); // RFC 2616 states that all unknown HTTP codes must be treated the same as - // the base code in their class: + // the base code in their class. if (!isset($responses[$code])) { $code = floor($code / 100) * 100; } @@ -393,7 +385,9 @@ function drupal_http_request($url, $headers = array(), $method = 'GET', $data = $result->code = $code; return $result; } -/* @} */ +/** + * @} End of "HTTP handling". + */ /** * Log errors in the database rather than displaying them to the user. @@ -436,9 +430,8 @@ function fix_gpc_magic() { /** * @name Conversion - * - * Converts data structures to a different type. * @{ + * Converts data structures to different types. */ /** @@ -473,13 +466,15 @@ function object2array($object) { return $array; } -/* @} */ + +/** + * @} End of "Conversion". + */ /** * @name Messages - * - * Frequently used messages. * @{ + * Frequently used messages. */ /** @@ -499,7 +494,9 @@ function message_na() { return t('n/a'); } -/* @} */ +/** + * @} End of "Messages". + */ /** * Initialize the localization system. @@ -525,23 +522,23 @@ function locale_initialize() { * Translate strings to the current locale. * * When using t(), try to put entire sentences and strings in one t() call. - * This makes it easier for translators. We are unafraid of HTML markup within - * translation strings if necessary. The suggested syntax for a link embedded - * within a translation string is for example: - * @verbatim + * This makes it easier for translators. HTML markup within translation strings + * is acceptable, if necessary. The suggested syntax for a link embedded + * within a translation string is: + * @code * $msg = t('You must log in below or <a href="%url">create a new * account</a> before viewing the next page.', array('%url' * => url('user/register'))); - * @endverbatim + * @endcode * We suggest the same syntax for links to other sites. This makes it easy to * change link URLs if needed (which happens often) without requiring updates * to translations. * * @param $string - * A string containing the english string to translate. + * A string containing the English string to translate. * @param $args * An associative array of replacements to make after translation. Incidences - * of any key in this array are replaces with the corresponding value. + * of any key in this array are replaced with the corresponding value. * @return * The translated string. */ @@ -572,10 +569,9 @@ function drupal_specialchars($input, $quotes = ENT_NOQUOTES) { } /** - * @name Validation - * - * Functions to validate user input. + * @defgroup validation Input validation * @{ + * Functions to validate user input. */ /** @@ -603,7 +599,7 @@ function valid_email_address($mail) { * @param $url * The URL to verify. * @param $absolute - * Whether the URL is absolute (beginning with a scheme such as http). + * Whether the URL is absolute (beginning with a scheme such as "http:"). * @return * TRUE if the URL is in a valid format. */ @@ -657,28 +653,33 @@ function valid_input_data($data) { return TRUE; } -/* @} */ +/** + * @} End of "defgroup validation". + */ /** * @defgroup search Search interface * @{ + * The Drupal search interface manages a global search mechanism. + * + * Modules may plug into this system to provide searches of different types of + * data. Most of the system is handled by search.module, so this must be enabled + * for all of the search features to work. */ /** - * Format a single result entry of a search query: + * Format a single result entry of a search query. + * + * Modules may implement hook_search_item() in order to override this default + * function to display search results. * - * @param $item a single search result as returned by <i>module</i>_search of - * type array('count' => ..., 'link' => ..., 'title' => ..., 'user' => ..., - * 'date' => ..., 'keywords' => ...) - * @param $type module type of this item + * @param $item + * A single search result as returned by hook_search(). The result should be + * an array with keys "count", "link", "title", "user", "date", and "keywords". + * @param $type + * The type of item found, such as "user" or "comment". */ function search_item($item, $type) { - - /* - ** Modules may implement hook_search_item() hook in order to overwrite - ** the default function to display search results. - */ - if (module_hook($type, 'search_item')) { $output = module_invoke($type, 'search_item', $item); } @@ -693,17 +694,22 @@ function search_item($item, $type) { /** * Render a generic search form. * - * "Generic" means "universal usable" - that is, usable not only from - * 'site.com/search', but also as a simple search box (without "Restrict search - * to", help text, etc) from theme's header etc. This means: provide options to - * only conditionally render certain parts of this form. + * This form must be usable not only within "http://example.com/search", but also + * as a simple search box (without "Restrict search to", help text, etc.), in the + * theme's header, and so forth. This means we must provide options to + * conditionally render certain parts of this form. * - * @param $action Form action. Defaults to 'site.com/search'. - * @param $keys string containing keywords for the search. - * @param $options != 0: Render additional form fields/text ("Restrict search - * to", help text, etc). + * @param $action + * Form action. Defaults to "search". + * @param $keys + * The search string entered by the user, containing keywords for the search. + * @param $options + * Whether to render the optional form fields and text ("Restrict search + * to", help text, etc.). + * @return + * An HTML string containing the search form. */ -function search_form($action = NULL, $keys = NULL, $options = NULL) { +function search_form($action = '', $keys = '', $options = FALSE) { $edit = $_POST['edit']; if (!$action) { @@ -728,8 +734,8 @@ function search_form($action = NULL, $keys = NULL, $options = NULL) { return form($output, 'post', $action); } -/* - * Collect the search results: +/** + * Perform a global search on the given keys, and return the formatted results. */ function search_data($keys = NULL) { $edit = $_POST['edit']; @@ -755,23 +761,28 @@ function search_data($keys = NULL) { } /** - * Display the search form and the resulting data. + * Display a search form for a particular type of data. * - * @param $type If set, search only nodes of this type. Otherwise, search all - * types. - * @param $action Form action. Defaults to 'site.com/search'. - * @param $keys Query string. Defaults to global $keys. - * @param $options != 0: Render additional form fields/text ("Restrict search - * to", help text, etc). + * @param $type + * The type of content to search within. + * @param $action + * Form action. Defaults to "search". + * @param $keys + * The search string entered by the user, containing keywords for the search. + * @param $options + * Whether to render the optional form fields and text ("Restrict search + * to", help text, etc.). + * @return + * An HTML string containing the search form and results. */ -function search_type($type, $action = NULL, $keys = NULL, $options = NULL) { +function search_type($type, $action = '', $keys = '', $options = FALSE) { $_POST['edit']['type'][$type] = 'on'; return search_form($action, $keys, $options) . '<br />'. search_data($keys); } /** - * @} end of defgroup search + * @} End of "defgroup search". */ function check_form($text) { @@ -783,10 +794,9 @@ function check_file($filename) { } /** - * @name Formatting - * - * Functions to format numbers, strings, dates, etc. + * @defgroup format Formatting * @{ + * Functions to format numbers, strings, dates, etc. */ /** @@ -1032,13 +1042,18 @@ function format_name($object) { return $output; } -/* @} */ +/** + * @} End of "defgroup format". + */ /** * @defgroup form Form generation * @{ + * Functions to enable output of HTML forms and form elements. * - * + * Drupal uses these functions to achieve consistency in its form presentation, + * while at the same time simplifying code and reducing the amount of HTML that + * must be explicily generated by modules. */ /** @@ -1500,7 +1515,7 @@ function form_weight($title = NULL, $name = 'weight', $value = 0, $delta = 10, $ } /** - * @} end of defgroup form + * @} End of "defgroup form". */ /** @@ -1527,11 +1542,9 @@ function url($path = NULL, $query = NULL, $fragment = NULL, $absolute = FALSE) { static $script; if (empty($script)) { - /* - ** On some webservers such as IIS we can't omit "index.php". As such we - ** generate "index.php?q=foo" instead of "?q=foo" on anything that is not - ** Apache. - */ + // On some web servers, such as IIS, we can't omit "index.php". So, we + // generate "index.php?q=foo" instead of "?q=foo" on anything that is not + // Apache. $script = (strpos($_SERVER['SERVER_SOFTWARE'], 'Apache') === false) ? 'index.php' : ''; } @@ -1745,10 +1758,8 @@ function drupal_xml_parser_create(&$data) { $encoding = $match[1]; } - /* - * Unsupported encodings are converted here into UTF-8. - * Requires the iconv, GNU recode or mbstring PHP extension. - */ + // Unsupported encodings are converted here into UTF-8. + // Requires the iconv, GNU recode or mbstring PHP extension. $php_supported = array('utf-8', 'iso-8859-1', 'us-ascii'); if (!in_array(strtolower($encoding), $php_supported)) { if (function_exists('iconv')) { @@ -1788,7 +1799,7 @@ function drupal_xml_parser_create(&$data) { * * Use this function whenever you want to chop off a string at an unsure * location. On the other hand, if you're sure that you're splitting on a - * character boundary (e.g. after using strpos or similar), you can safely use + * character boundary (e.g. after using strpos() or similar), you can safely use * substr() instead. * * @param $string @@ -1811,24 +1822,21 @@ function truncate_utf8($string, $len) { } /** - * Encodes MIME/HTTP header values that contain non US-ASCII - * characters. + * Encodes MIME/HTTP header values that contain non US-ASCII characters. * - * Example: mime_header_encode('tést.txt') returns '=?UTF-8?B?dMOpc3QudHh0?=' + * For example, mime_header_encode('tést.txt') returns "=?UTF-8?B?dMOpc3QudHh0?=". * - * For more info: http://www.rfc-editor.org/rfc/rfc2047.txt + * See http://www.rfc-editor.org/rfc/rfc2047.txt for more information. * + * Notes: + * - Only encode strings that contain non-ASCII characters. + * - The chunks come in groupings of 4 bytes when using base64 encoding. + * - trim() is used to ensure that no extra spacing is added by chunk_split() or + * preg_replace(). + * - Using \n as the chunk separator may cause problems on some systems and may + * have to be changed to \r\n or \r. */ function mime_header_encode($string, $charset = 'UTF-8') { - // Notes: - // - Only encode strings that contain non-ASCII characters. - // - The chunks come in groupings of 4 bytes when using base64 - // encoded. - // - trim() is used to ensure that no extra spacing is added by - // chunk_split() or preg_replace(). - // - Using \n as the chunk separator may cause problems on some - // systems and may have to be changed to \r\n or \r. - if (!preg_match('/^[\x20-\x7E]*$/', $string)) { $chunk_size = 75 - 7 - strlen($charset); $chunk_size -= $chunk_size % 4; @@ -1839,12 +1847,18 @@ function mime_header_encode($string, $charset = 'UTF-8') { } /** - * Wrapper around PHP's eval(). Uses output buffering to capture both returned - * and printed text. Unlike eval(), we require code to be surrounded by <?php ?> - * tags (in other words, we evaluate the code as if it were a stand-alone PHP - * file). + * Evaluate a string of PHP code. * - * @param $code The code to evaluate + * This is a wrapper around PHP's eval(). It uses output buffering to capture both + * returned and printed text. Unlike eval(), we require code to be surrounded by + * <?php ?> tags; in other words, we evaluate the code as if it were a stand-alone + * PHP file. + * + * @param $code + * The code to evaluate. + * @return + * A string containing the printed output of the code, followed by the returned + * output of the code. */ function drupal_eval($code) { ob_start(); @@ -1861,13 +1875,13 @@ include_once 'includes/tablesort.inc'; include_once 'includes/file.inc'; include_once 'includes/xmlrpc.inc'; -// set error handler: +// Set the Drupal custom error handler. set_error_handler('error_handler'); -// spit out the correct charset http header +// Emit the correct charset HTTP header. drupal_set_header('Content-Type: text/html; charset=utf-8'); -// initialize the _GET['q'] prior to loading the modules and invoking their 'init' hook: +// Initialize $_GET['q'] prior to loading modules and invoking hook_init(). if (!empty($_GET['q'])) { $_GET['q'] = drupal_get_normal_path(trim($_GET['q'], '/')); } @@ -1875,19 +1889,19 @@ else { $_GET['q'] = drupal_get_normal_path(variable_get('site_frontpage', 'node')); } -// initialize installed modules: +// Initialize all enabled modules. module_init(); if ($_REQUEST && !user_access('bypass input data check')) { if (!valid_input_data($_REQUEST)) { - die('terminated request because of suspicious input data'); + die('Terminated request because of suspicious input data.'); } } -// initialize localization system: +// Initialize the localization system. $locale = locale_initialize(); -// initialize theme: +// Initialize the enabled theme. $theme = init_theme(); ?> diff --git a/includes/database.inc b/includes/database.inc index ddfaf5d4c..772861149 100644 --- a/includes/database.inc +++ b/includes/database.inc @@ -9,6 +9,7 @@ /** * @defgroup database Database abstraction layer * @{ + * Allow the use of different database servers using the same code base. * * Drupal provides a slim database abstraction layer to provide developers with * the ability to support multiple database servers easily. The intent of this @@ -119,7 +120,7 @@ function db_set_active($name = 'default') { } /** - * @} end of defgroup database + * @} End of "defgroup database". */ // Initialize the default database. diff --git a/includes/database.mysql.inc b/includes/database.mysql.inc index ff0919fdc..e3c46557d 100644 --- a/includes/database.mysql.inc +++ b/includes/database.mysql.inc @@ -7,7 +7,7 @@ */ /** - * @addtogroup database + * @ingroup database * @{ */ @@ -286,7 +286,7 @@ function db_decode_blob($data) { } /** - * @} end of addtogroup database + * @} End of "ingroup database". */ ?> diff --git a/includes/database.pgsql.inc b/includes/database.pgsql.inc index 9ea863d51..95a36d3fa 100644 --- a/includes/database.pgsql.inc +++ b/includes/database.pgsql.inc @@ -3,11 +3,11 @@ /** * @file - * Database interface code for postgresql database servers. + * Database interface code for PostgreSQL database servers. */ /** - * @addtogroup database + * @ingroup database * @{ */ @@ -279,7 +279,7 @@ function db_decode_blob($data) { } /** - * @} end of addtogroup database + * @} End of "ingroup database". */ ?> diff --git a/includes/file.inc b/includes/file.inc index 4018e5acc..7fae2c796 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -8,8 +8,8 @@ /** * @defgroup file File interface - * Common file handling functions. * @{ + * Common file handling functions. */ define('FILE_DOWNLOADS_PUBLIC', 1); diff --git a/includes/menu.inc b/includes/menu.inc index 26354247d..9ac5a2647 100644 --- a/includes/menu.inc +++ b/includes/menu.inc @@ -9,6 +9,7 @@ /** * @defgroup menu Menu system * @{ + * Define the navigation menus, and route page requests to code based on URLs. * * The Drupal menu system drives both the navigation system from a user * perspective and the callback system that Drupal uses to respond to URLs @@ -66,10 +67,11 @@ */ /** - * @name Menu Flags + * @name Menu flags * @{ * Flags for use in the "type" attribute of menu items. */ + define('MENU_IS_ROOT', 0x0001); define('MENU_VISIBLE_IN_TREE', 0x0002); define('MENU_VISIBLE_IN_BREADCRUMB', 0x0004); @@ -79,12 +81,13 @@ define('MENU_MODIFIED_BY_ADMIN', 0x0020); define('MENU_CREATED_BY_ADMIN', 0x0040); define('MENU_IS_LOCAL_TASK', 0x0080); define('MENU_LINKS_TO_PARENT', 0x0200); + /** - * @} + * @} End of "Menu flags". */ /** - * @name Menu Item Types + * @name Menu item types * @{ * Menu item definitions provide one of these constants, which are shortcuts for * combinations of the above flags. @@ -148,7 +151,7 @@ define('MENU_CUSTOM_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB | M define('MENU_CUSTOM_MENU', MENU_IS_ROOT | MENU_VISIBLE_IN_TREE | MENU_CREATED_BY_ADMIN | MENU_MODIFIABLE_BY_ADMIN); /** - * @} + * @} End of "Menu item types". */ /** @@ -156,11 +159,13 @@ define('MENU_CUSTOM_MENU', MENU_IS_ROOT | MENU_VISIBLE_IN_TREE | MENU_CREATED_BY * @{ * Status codes for menu callbacks. */ + define('MENU_FOUND', 1); define('MENU_NOT_FOUND', 2); define('MENU_ACCESS_DENIED', 3); + /** - * @} + * @} End of "Menu status codes". */ /** @@ -510,16 +515,9 @@ function menu_rebuild() { } /** - * @} end of defgroup menu - */ - -/** - * @addtogroup themeable - * @{ - */ - -/** * Returns a rendered menu tree. + * + * @ingroup themeable */ function theme_menu_tree($pid = 1, $all = FALSE) { $menu = menu_get_menu(); @@ -550,6 +548,8 @@ function theme_menu_tree($pid = 1, $all = FALSE) { * * @param $mid * The menu ID to render. + * + * @ingroup themeable */ function theme_menu_item($mid) { $menu = menu_get_menu(); @@ -565,6 +565,8 @@ function theme_menu_item($mid) { /** * Returns the rendered local tasks. The default implementation renders * them as tabs. + * + * @ingroup themeable */ function theme_menu_local_tasks() { $local_tasks = menu_get_local_tasks(); @@ -599,6 +601,8 @@ function theme_menu_local_tasks() { * The menu ID to render. * @param $active * Whether this tab or a subtab is the active menu item. + * + * @ingroup themeable */ function theme_menu_local_task($mid, $active) { if ($active) { @@ -610,7 +614,7 @@ function theme_menu_local_task($mid, $active) { } /** - * @} end of addtogroup themeable + * @} End of "defgroup menu". */ /** diff --git a/includes/module.inc b/includes/module.inc index 62c2cbae9..c244c23f9 100644 --- a/includes/module.inc +++ b/includes/module.inc @@ -170,6 +170,8 @@ function module_exist($module) { /** * @defgroup hooks Hooks + * @{ + * Allow modules to interact with the Drupal core. * * Drupal's module system is based on the concept of "hooks". A hook is a PHP * function that is named foo_bar(), where "foo" is the name of the module (whose @@ -185,8 +187,6 @@ function module_exist($module) { * the module name is the hook definitions. For example, if the module file is * called example.module, then hook_help() as implemented by that module would be * defined as example_help(). - * - * @{ */ /** @@ -250,7 +250,7 @@ function module_invoke_all($hook, $a1 = NULL, $a2 = NULL, $a3 = NULL, $a4 = NULL } /** - * @} end of defgroup hooks + * @} End of "defgroup hooks". */ ?> diff --git a/includes/pager.inc b/includes/pager.inc index f3546a269..913603d7a 100644 --- a/includes/pager.inc +++ b/includes/pager.inc @@ -8,7 +8,6 @@ /** * Perform a paged database query. - * @ingroup database * * Use this function when doing select queries you wish to be able to page. The * pager uses LIMIT-based queries to fetch only the records required to render a @@ -44,6 +43,8 @@ * @return * A database query result resource, or FALSE if the query was not executed * correctly. + * + * @ingroup database */ function pager_query($query, $limit = 10, $element = 0, $count_query = NULL) { global $pager_from_array, $pager_total; @@ -66,11 +67,6 @@ function pager_query($query, $limit = 10, $element = 0, $count_query = NULL) { } /** - * @addtogroup themeable - * @{ - */ - -/** * Format a query pager. * * Menu callbacks that display paged query results should call theme('pager') to @@ -86,6 +82,8 @@ function pager_query($query, $limit = 10, $element = 0, $count_query = NULL) { * An associative array of query string parameters to append to the pager links. * @return * An HTML string that generates the query pager. + * + * @ingroup themeable */ function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = array()) { global $pager_total; @@ -105,14 +103,10 @@ function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = a } /** - * @} end of addtogroup themeable - */ - -/** * @name Pager pieces - * Use these pieces to construct your own custom pagers in your theme. Note - * that you should NOT modify this file to customize your pager. * @{ + * Use these pieces to construct your own custom pagers in your theme. Note that + * you should NOT modify this file to customize your pager. */ /** @@ -282,9 +276,9 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = '', $attributes $pager_max++; $pager_current++; } -// End of marker calculations. + // End of marker calculations. -// Prepare for generation loop. + // Prepare for generation loop. $i = (int)$pager_first; if ($pager_last > $pager_max) { // Adjust "center" if at end of query. @@ -296,7 +290,7 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = '', $attributes $pager_last = $pager_last + (1 - $i); $i = 1; } -// End of generation loop preparation. + // End of generation loop preparation. // When there is more than one page, create the pager list. if ($i != $pager_max) { @@ -325,7 +319,9 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = '', $attributes return $output; } -/* @} End of member group pager pieces */ +/** + * @} End of "Pager pieces". + */ /** * Format a link to a specific query result page. @@ -360,14 +356,14 @@ function pager_link($from_new, $element, $attributes = array()) { function pager_load_array($value, $element, $old_array) { $new_array = $old_array; - // look for empty elements + // Look for empty elements. for ($i = 0; $i < $element; $i++) { if (!$new_array[$i]) { - // load found empty element with 0 + // Load found empty element with 0. $new_array[$i] = 0; } } - // update the changed element + // Update the changed element. $new_array[$element] = (int)$value; return $new_array; } diff --git a/includes/tablesort.inc b/includes/tablesort.inc index 064b8e824..d41c3aab3 100644 --- a/includes/tablesort.inc +++ b/includes/tablesort.inc @@ -33,7 +33,6 @@ function tablesort_pager() { /** * Create an SQL sort clause. - * @ingroup database * * This function produces the ORDER BY clause to insert in your SQL queries, * assuring that the returned database table rows match the sort order chosen @@ -46,6 +45,8 @@ function tablesort_pager() { * Useful for sorting by important attributes like "sticky" first. * @return * An SQL string to append to the end of a query. + * + * @ingroup database */ function tablesort_sql($header, $before = '') { $ts = tablesort_init($header); diff --git a/includes/theme.inc b/includes/theme.inc index d9f8a5de6..57c2b1724 100644 --- a/includes/theme.inc +++ b/includes/theme.inc @@ -322,13 +322,14 @@ function theme_get_styles() { /** * @defgroup themeable Themeable functions * @{ + * Functions that display HTML, and which can be customized by themes. * * All functions that produce HTML for display should be themeable. This means * that they should be named with the theme_ prefix, and invoked using theme() * rather than being called directly. This allows themes to override the display * of any Drupal object. * - * @see theme.inc + * The theme system is described and defined in theme.inc. */ /** @@ -805,7 +806,7 @@ function theme_blocks($region) { return $output; } /** - * @} end of defgroup themeable + * @} End of "defgroup themeable". */ function _theme_table_cell($cell, $header = 0) { diff --git a/modules/aggregator.module b/modules/aggregator.module index 65cfbf52a..57b98c50b 100644 --- a/modules/aggregator.module +++ b/modules/aggregator.module @@ -1019,12 +1019,11 @@ function aggregator_page_categories() { } /** - * @addtogroup themeable - * @{ + * Format a news feed. + * + * @ingroup themeable */ - function theme_aggregator_feed($feed) { - $output = ''; if ($feed->image) { @@ -1048,6 +1047,11 @@ function theme_aggregator_feed($feed) { return $output; } +/** + * Format an individual feed item for display in the block. + * + * @ingroup themeable + */ function theme_aggregator_block_item($item, $feed = 0) { global $user; @@ -1057,18 +1061,20 @@ function theme_aggregator_block_item($item, $feed = 0) { } } - // external link + // Display the external link to the item. $output .= "<a href=\"$item->link\">$item->title</a>\n"; return $output; } /** - * Returns a themed item heading for summary pages located at - * aggregator/sources and aggregator/categories. + * Return a themed item heading for summary pages located at "aggregator/sources" + * and "aggregator/categories". * * @param $item The item object from the aggregator module. * @return A string containing the output. + * + * @ingroup themeable */ function theme_aggregator_summary_item($item) { $output = '<a href="'. check_url($item->link) .'">'. $item->title .'</a> <span class="age">'. t('%age old', array('%age' => format_interval(time() - $item->timestamp))) .'</span>'; @@ -1078,6 +1084,11 @@ function theme_aggregator_summary_item($item) { return $output ."\n"; } +/** + * Format an individual feed item for display on the aggregator page. + * + * @ingroup themeable + */ function theme_aggregator_page_item($item) { static $last; @@ -1113,6 +1124,4 @@ function theme_aggregator_page_item($item) { return $output; } -/** @} End of addtogroup themeable */ - ?> diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module index 65cfbf52a..57b98c50b 100644 --- a/modules/aggregator/aggregator.module +++ b/modules/aggregator/aggregator.module @@ -1019,12 +1019,11 @@ function aggregator_page_categories() { } /** - * @addtogroup themeable - * @{ + * Format a news feed. + * + * @ingroup themeable */ - function theme_aggregator_feed($feed) { - $output = ''; if ($feed->image) { @@ -1048,6 +1047,11 @@ function theme_aggregator_feed($feed) { return $output; } +/** + * Format an individual feed item for display in the block. + * + * @ingroup themeable + */ function theme_aggregator_block_item($item, $feed = 0) { global $user; @@ -1057,18 +1061,20 @@ function theme_aggregator_block_item($item, $feed = 0) { } } - // external link + // Display the external link to the item. $output .= "<a href=\"$item->link\">$item->title</a>\n"; return $output; } /** - * Returns a themed item heading for summary pages located at - * aggregator/sources and aggregator/categories. + * Return a themed item heading for summary pages located at "aggregator/sources" + * and "aggregator/categories". * * @param $item The item object from the aggregator module. * @return A string containing the output. + * + * @ingroup themeable */ function theme_aggregator_summary_item($item) { $output = '<a href="'. check_url($item->link) .'">'. $item->title .'</a> <span class="age">'. t('%age old', array('%age' => format_interval(time() - $item->timestamp))) .'</span>'; @@ -1078,6 +1084,11 @@ function theme_aggregator_summary_item($item) { return $output ."\n"; } +/** + * Format an individual feed item for display on the aggregator page. + * + * @ingroup themeable + */ function theme_aggregator_page_item($item) { static $last; @@ -1113,6 +1124,4 @@ function theme_aggregator_page_item($item) { return $output; } -/** @} End of addtogroup themeable */ - ?> diff --git a/modules/filter.module b/modules/filter.module index 849c9ca4d..5c6931eed 100644 --- a/modules/filter.module +++ b/modules/filter.module @@ -558,11 +558,9 @@ function filter_list_format($format) { /** * @name Filtering functions - * + * @{ * Modules which need to have content filtered can use these functions to * interact with the filter system. - * - * @{ */ /** @@ -666,7 +664,9 @@ function filter_access($format) { return isset($formats[$format]); } } -/* @} */ +/** + * @} End of "Filtering functions". + */ /** * Menu callback; show a page with long filter tips. @@ -710,16 +710,9 @@ function _filter_tips($format, $long = false) { } /** - * @addtogroup themeable - * @{ - */ - -/** - * Format filter tips + * Format a set of filter tips. * - * @param $tips - * @param $long - * @param $extra + * @ingroup themeable */ function theme_filter_tips($tips, $long = false, $extra = '') { $output = ''; @@ -758,13 +751,10 @@ function theme_filter_tips($tips, $long = false, $extra = '') { return $output; } -/** @} End of addtogroup themeable */ - /** * @name Standard filters - * - * Filters implemented by the filter.module. * @{ + * Filters implemented by the filter.module. */ /** @@ -879,6 +869,8 @@ function _filter_autop($text) { return $text; } -/* @} */ +/** + * @} End of "Standard filters". + */ ?> diff --git a/modules/filter/filter.module b/modules/filter/filter.module index 849c9ca4d..5c6931eed 100644 --- a/modules/filter/filter.module +++ b/modules/filter/filter.module @@ -558,11 +558,9 @@ function filter_list_format($format) { /** * @name Filtering functions - * + * @{ * Modules which need to have content filtered can use these functions to * interact with the filter system. - * - * @{ */ /** @@ -666,7 +664,9 @@ function filter_access($format) { return isset($formats[$format]); } } -/* @} */ +/** + * @} End of "Filtering functions". + */ /** * Menu callback; show a page with long filter tips. @@ -710,16 +710,9 @@ function _filter_tips($format, $long = false) { } /** - * @addtogroup themeable - * @{ - */ - -/** - * Format filter tips + * Format a set of filter tips. * - * @param $tips - * @param $long - * @param $extra + * @ingroup themeable */ function theme_filter_tips($tips, $long = false, $extra = '') { $output = ''; @@ -758,13 +751,10 @@ function theme_filter_tips($tips, $long = false, $extra = '') { return $output; } -/** @} End of addtogroup themeable */ - /** * @name Standard filters - * - * Filters implemented by the filter.module. * @{ + * Filters implemented by the filter.module. */ /** @@ -879,6 +869,8 @@ function _filter_autop($text) { return $text; } -/* @} */ +/** + * @} End of "Standard filters". + */ ?> diff --git a/modules/forum.module b/modules/forum.module index 9be309d16..478827107 100644 --- a/modules/forum.module +++ b/modules/forum.module @@ -491,21 +491,9 @@ function forum_page($tid = 0, $display = 'all') { } /** - * @addtogroup themeable - * @{ - */ - -/** * Format the forum body. * - * @param forums - * @param topics - * @param parents - * @param tid - * @param sortby - * @param forum_per_page - * - * @return the output for the forum body. + * @ingroup themeable */ function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_per_page) { global $user; @@ -575,11 +563,7 @@ function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_p /** * Format the forum listing. * - * @param forums - * @param parents - * @param tid - * - * @return output for the forum listing. + * @ingroup themeable */ function theme_forum_list($forums, $parents, $tid) { global $user; @@ -632,12 +616,7 @@ function theme_forum_list($forums, $parents, $tid) { /** * Format the topic listing. * - * @param tid - * @param topics - * @param sortby - * @param forum_per_page - * - * @return output for the topic list. + * @ingroup themeable */ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) { global $forum_topic_list_header; @@ -674,8 +653,6 @@ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) { return $output; } -/** @} End of addtogroup themeable */ - function _forum_icon($new_posts, $num_posts = 0, $comment_mode = 0, $sticky = 0) { $base_path = variable_get('forum_icon_path', ''); diff --git a/modules/forum/forum.module b/modules/forum/forum.module index 9be309d16..478827107 100644 --- a/modules/forum/forum.module +++ b/modules/forum/forum.module @@ -491,21 +491,9 @@ function forum_page($tid = 0, $display = 'all') { } /** - * @addtogroup themeable - * @{ - */ - -/** * Format the forum body. * - * @param forums - * @param topics - * @param parents - * @param tid - * @param sortby - * @param forum_per_page - * - * @return the output for the forum body. + * @ingroup themeable */ function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_per_page) { global $user; @@ -575,11 +563,7 @@ function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_p /** * Format the forum listing. * - * @param forums - * @param parents - * @param tid - * - * @return output for the forum listing. + * @ingroup themeable */ function theme_forum_list($forums, $parents, $tid) { global $user; @@ -632,12 +616,7 @@ function theme_forum_list($forums, $parents, $tid) { /** * Format the topic listing. * - * @param tid - * @param topics - * @param sortby - * @param forum_per_page - * - * @return output for the topic list. + * @ingroup themeable */ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) { global $forum_topic_list_header; @@ -674,8 +653,6 @@ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) { return $output; } -/** @} End of addtogroup themeable */ - function _forum_icon($new_posts, $num_posts = 0, $comment_mode = 0, $sticky = 0) { $base_path = variable_get('forum_icon_path', ''); diff --git a/modules/node.module b/modules/node.module index 10cb1b3c9..d750593cb 100644 --- a/modules/node.module +++ b/modules/node.module @@ -65,13 +65,12 @@ function node_cron() { } /** - * Menu callback; presents node-specific imformation from admin/help. + * Menu callback; presents node-specific imformation from "admin/help". */ function node_help_page() { print theme('page', node_help('admin/help#node')); } - /** * Gather a listing of links to nodes. * @@ -131,7 +130,7 @@ function node_last_viewed($nid) { } /** - * Determines whether the supplied timestamp is newer than the user's last view + * Determine whether the supplied timestamp is newer than the user's last view * of a given node. * * @param $nid @@ -156,7 +155,7 @@ function node_is_new($nid, $timestamp) { } /** - * Autogenerate a teaser for the given body text. + * Automatically generate a teaser for the given body text. */ function node_teaser($body) { @@ -235,7 +234,7 @@ function node_teaser($body) { /** - * Determines the module that defines the node type of the given node. + * Determine the module that defines the node type of the given node. * * @param &$node * Either a node object, a node array, or a string containing the node type. @@ -273,7 +272,7 @@ function node_get_module_name($node) { * Get a list of all the defined node types. * * @return - * An list of all node types. + * A list of all node types. */ function node_list() { $types = array(); @@ -703,7 +702,7 @@ function node_admin_edit($node) { } /** - * Generate the content administation overview. + * Generate the content administration overview. */ function node_admin_nodes() { $filters = array( @@ -835,7 +834,7 @@ function node_default_settings() { } /** - * Generates an overview table of older revisions of a node. + * Generate an overview table of older revisions of a node. */ function node_revision_overview($nid) { if (user_access('administer nodes')) { @@ -1028,7 +1027,7 @@ function node_feed($nodes = 0, $channel = array()) { } /** - * Preform validation checks on the given node. + * Perform validation checks on the given node. */ function node_validate($node) { global $user; @@ -1670,11 +1669,9 @@ function node_access_join_sql($node_alias = 'n', $node_access_alias = 'na') { */ function node_access_where_sql($op = 'view', $node_access_alias = 'na') { if (user_access('administer nodes')) { - /** - * This number is being used in a SQL query in a boolean nature. - * It is "'1'" instead of "1" for database compatibility, as both - * Postgres and Mysql treat it as boolean in this case. - */ + // This number is being used in a SQL query as a boolean. + // It is "'1'" instead of "1" for database compatibility, as both + // PostgreSQL and MySQL treat it as boolean in this case. return "'1'"; } @@ -1718,7 +1715,7 @@ function node_access_grants($op, $uid = NULL) { } /** - * @} end of defgroup node_access + * @} End of "defgroup node_access". */ ?> diff --git a/modules/node/node.module b/modules/node/node.module index 10cb1b3c9..d750593cb 100644 --- a/modules/node/node.module +++ b/modules/node/node.module @@ -65,13 +65,12 @@ function node_cron() { } /** - * Menu callback; presents node-specific imformation from admin/help. + * Menu callback; presents node-specific imformation from "admin/help". */ function node_help_page() { print theme('page', node_help('admin/help#node')); } - /** * Gather a listing of links to nodes. * @@ -131,7 +130,7 @@ function node_last_viewed($nid) { } /** - * Determines whether the supplied timestamp is newer than the user's last view + * Determine whether the supplied timestamp is newer than the user's last view * of a given node. * * @param $nid @@ -156,7 +155,7 @@ function node_is_new($nid, $timestamp) { } /** - * Autogenerate a teaser for the given body text. + * Automatically generate a teaser for the given body text. */ function node_teaser($body) { @@ -235,7 +234,7 @@ function node_teaser($body) { /** - * Determines the module that defines the node type of the given node. + * Determine the module that defines the node type of the given node. * * @param &$node * Either a node object, a node array, or a string containing the node type. @@ -273,7 +272,7 @@ function node_get_module_name($node) { * Get a list of all the defined node types. * * @return - * An list of all node types. + * A list of all node types. */ function node_list() { $types = array(); @@ -703,7 +702,7 @@ function node_admin_edit($node) { } /** - * Generate the content administation overview. + * Generate the content administration overview. */ function node_admin_nodes() { $filters = array( @@ -835,7 +834,7 @@ function node_default_settings() { } /** - * Generates an overview table of older revisions of a node. + * Generate an overview table of older revisions of a node. */ function node_revision_overview($nid) { if (user_access('administer nodes')) { @@ -1028,7 +1027,7 @@ function node_feed($nodes = 0, $channel = array()) { } /** - * Preform validation checks on the given node. + * Perform validation checks on the given node. */ function node_validate($node) { global $user; @@ -1670,11 +1669,9 @@ function node_access_join_sql($node_alias = 'n', $node_access_alias = 'na') { */ function node_access_where_sql($op = 'view', $node_access_alias = 'na') { if (user_access('administer nodes')) { - /** - * This number is being used in a SQL query in a boolean nature. - * It is "'1'" instead of "1" for database compatibility, as both - * Postgres and Mysql treat it as boolean in this case. - */ + // This number is being used in a SQL query as a boolean. + // It is "'1'" instead of "1" for database compatibility, as both + // PostgreSQL and MySQL treat it as boolean in this case. return "'1'"; } @@ -1718,7 +1715,7 @@ function node_access_grants($op, $uid = NULL) { } /** - * @} end of defgroup node_access + * @} End of "defgroup node_access". */ ?> diff --git a/modules/search.module b/modules/search.module index 4143cfda2..f42c1e2ba 100644 --- a/modules/search.module +++ b/modules/search.module @@ -246,7 +246,7 @@ function update_index($search_array) { // Trash any existing entries in the search index for this node, // in case it is a modified node. - db_query("DELETE from {search_index} where lno = '". $node['lno'] ."' and type = '". $node_type ."'"); + db_query("DELETE from {search_index} WHERE lno = '". $node['lno'] ."' AND type = '". $node_type ."'"); // Build the word list (teaser not included, as it would give a // false count of the number of hits). diff --git a/modules/search/search.module b/modules/search/search.module index 4143cfda2..f42c1e2ba 100644 --- a/modules/search/search.module +++ b/modules/search/search.module @@ -246,7 +246,7 @@ function update_index($search_array) { // Trash any existing entries in the search index for this node, // in case it is a modified node. - db_query("DELETE from {search_index} where lno = '". $node['lno'] ."' and type = '". $node_type ."'"); + db_query("DELETE from {search_index} WHERE lno = '". $node['lno'] ."' AND type = '". $node_type ."'"); // Build the word list (teaser not included, as it would give a // false count of the number of hits). |