Commit b84b6e42 authored by Dries's avatar Dries

- Patch #10663 by JonBob: documentation improvements: fixed some typos and improved consistency to the use of Doxygen/api.module commands in the comments.
parent e891a878
......@@ -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';
......
......@@ -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') {
......
<?php
/* $Id$ */
// $Id$
/**
* @file
......@@ -393,13 +393,6 @@ function watchdog($type, $message, $link = NULL) {
db_query("INSERT INTO {watchdog} (uid, type, message, link, location, hostname, timestamp) VALUES (%d, '%s', '%s', '%s', '%s', '%s', %d)", $user->uid, $type, $message, $link, request_uri(), $_SERVER['REMOTE_ADDR'], time());
}
/**
* @name Page messages
*
* Functions to get and set the message of the current page.
* @{
*/
/**
* Set a message for the user to see.
*
......@@ -436,8 +429,6 @@ function drupal_get_messages() {
return $messages;
}
/* @} */
unset($conf);
$config = conf_init();
......@@ -448,4 +439,5 @@ function drupal_get_messages() {
// Initialize configuration variables, using values from conf.php if available.
$conf = variable_init(isset($conf) ? $conf : array());
?>
This diff is collapsed.
......@@ -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.
......
......@@ -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".
*/
?>
......@@ -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".
*/
?>
......@@ -8,8 +8,8 @@
/**
* @defgroup file File interface
* Common file handling functions.
* @{
* Common file handling functions.
*/
define('FILE_DOWNLOADS_PUBLIC', 1);
......
......@@ -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_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_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 @@
* @{
* Status codes for menu callbacks.
*/
define('MENU_FOUND', 1);
define('MENU_NOT_FOUND', 2);
define('MENU_ACCESS_DENIED', 3);
/**
* @}
* @} End of "Menu status codes".
*/
/**
......@@ -509,17 +514,10 @@ function menu_rebuild() {
_menu_build();
}
/**
* @} 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".
*/
/**
......
......@@ -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".
*/
?>
......@@ -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;
......@@ -65,11 +66,6 @@ function pager_query($query, $limit = 10, $element = 0, $count_query = NULL) {
return call_user_func_array('db_query_range', array_merge(array($query), $args, array((int)$pager_from_array[$element], (int)$limit)));
}
/**
* @addtogroup themeable
* @{
*/
/**
* Format a query pager.
*
......@@ -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;
......@@ -104,15 +102,11 @@ 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;
}
......
......@@ -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);
......
......@@ -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) {
......
......@@ -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 */
?>
......@@ -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 */
?>
......@@ -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".
*/
?>
......@@ -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".
*/
?>
......@@ -490,22 +490,10 @@ 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', '');
......
......@@ -490,22 +490,10 @@ 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