Commit 3904790e authored by Dries's avatar Dries

- Tidied up the DoxyGen comments. Patch by Kjartan.

parent bea3dbb7
......@@ -2,11 +2,11 @@
// $Id$
/**
@name drupal_title
Functions to get and set the title of the current page.
@{
**/
* @name drupal_title
*
* Functions to get and set the title of the current page.
* @{
*/
function drupal_set_title($title = NULL) {
static $stored_title;
......@@ -28,11 +28,11 @@ function drupal_get_title() {
// @}
/**
@name drupal_message
Functions to get and set the message of the current page.
@{
**/
* @name drupal_message
*
* Functions to get and set the message of the current page.
* @{
*/
function drupal_set_message($message = NULL, $type = "status") {
static $stored_message;
......@@ -50,14 +50,14 @@ function drupal_get_message() {
// @}
/**
@name drupal_breadcrumb
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.
@{
**/
* @name drupal_breadcrumb
*
* 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.
* @{
*/
function drupal_set_breadcrumb($breadcrumb = NULL) {
static $stored_breadcrumb;
......@@ -80,8 +80,8 @@ function drupal_get_breadcrumb() {
// @}
/**
Build the alias/path array
**/
* Build the alias/path array
*/
function drupal_get_path_map($action = "") {
static $cache;
......@@ -238,10 +238,10 @@ function drupal_specialchars($input, $quotes = ENT_NOQUOTES) {
}
/**
* Verify the syntax of the given e-mail address. Empty e-mail addresses
* are allowed. See RFC 2822 for details.
* Verify the syntax of the given e-mail address. Empty e-mail addresses are
* allowed. See RFC 2822 for details.
*
* @param $mail a email address
* @param $mail a email address
*/
function valid_email_address($mail) {
$user = '[a-zA-Z0-9_\-\.\+\^!#\$%&*+\/\=\?\`\|\{\}~\']+';
......@@ -260,7 +260,7 @@ function valid_email_address($mail) {
/**
* Verify the syntax of the given URL.
*
* @param $url an URL
* @param $url an URL
*/
function valid_url($url) {
......@@ -275,10 +275,10 @@ function valid_url($url) {
/**
* Format a single result entry of a search query:
*
* @param $item a single search result as returned by <i>module</i>_search of
* @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
* "date" => ..., "keywords" => ...)
* @param $type module type of this item
*/
function search_item($item, $type) {
......@@ -303,15 +303,14 @@ 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 seach 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.
* 'site.com/search', but also as a simple seach 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.
*
* @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 '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).
*/
function search_form($action = NULL, $keys = NULL, $options = NULL) {
......@@ -367,12 +366,12 @@ function search_data($keys = NULL) {
/**
* Display the search form and the resulting 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 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).
*/
function search_type($type, $action = NULL, $keys = NULL, $options = NULL) {
......@@ -607,17 +606,16 @@ function format_rss_item($title, $link, $description, $args = array()) {
/**
* Formats a string with a count of items so that the string is pluralized
* correctly.
* format_plural calls t() by itself, make sure not to pass already localized
* strings to it.
* correctly. format_plural calls t() by itself, make sure not to pass already
* localized strings to it.
*
* @param $count The item count to display.
* @param $singular The string for the singular case. Please make sure it's clear
* this is singular, to ease translation. ("1 new comment" instead of
* "1 new").
* @param $plural The string for the plrual case. Please make sure it's clear
* this is plural, to ease translation. Use %count in places of the
* item count, as in "%count new comments".
* @param $count The item count to display.
* @param $singular The string for the singular case. Please make sure it's
* clear this is singular, to ease translation. ("1 new comment" instead of "1
* new").
* @param $plural The string for the plrual case. Please make sure it's clear
* this is plural, to ease translation. Use %count in places of the item
* count, as in "%count new comments".
*/
function format_plural($count, $singular, $plural) {
return t($count == 1 ? $singular : $plural, array("%count" => $count));
......
......@@ -24,8 +24,9 @@ function db_connect($url) {
/**
* Runs a query in the database.
*
* @param $query SQL query, followed by a variable number of arguments which are substituted into query by sprintf.
* @return a MySQL result or FALSE if the query was not executed correctly.
* @param $query SQL query, followed by a variable number of arguments which
* are substituted into query by sprintf.
* @return a MySQL result or FALSE if the query was not executed correctly.
*/
function db_query($query) {
$args = func_get_args();
......@@ -148,8 +149,11 @@ function db_affected_rows() {
/**
* Runs a LIMIT query in the database.
*
* @param $query SQL query, followed by a variable number of arguments which are substituted into query by sprintf, followed by 'from' and 'count' parameters. 'from' is the row to start fetching, 'count' the numbers of rows to fetch.
* @return a MySQL result or FALSE if the query was not executed correctly.
* @param $query SQL query, followed by a variable number of arguments which
* are substituted into query by sprintf, followed by 'from' and 'count'
* parameters. 'from' is the row to start fetching, 'count' the numbers of
* rows to fetch.
* @return a MySQL result or FALSE if the query was not executed correctly.
*/
function db_query_range($query) {
$args = func_get_args();
......
......@@ -18,8 +18,9 @@ function db_connect($url) {
/**
* Runs a query in the database.
*
* @param $query SQL query, followed by a variable number of arguments which are substituted into query by sprintf.
* @return a DB_Result object or a DB_Error
* @param $query SQL query, followed by a variable number of arguments which
* are substituted into query by sprintf.
* @return a DB_Result object or a DB_Error
*/
function db_query($query) {
......@@ -145,8 +146,11 @@ function db_affected_rows() {
/**
* Runs a LIMIT query in the database.
*
* @param $query SQL query followed by a variable number of arguments which are substituted into query by sprintf, followed by 'from' and 'count' parameters. 'from' is the row to start fetching, 'count' the numbers of rows to fetch.
* @return a DB_Result object or a DB_Error
* @param $query SQL query followed by a variable number of arguments which
* are substituted into query by sprintf, followed by 'from' and 'count'
* parameters. 'from' is the row to start fetching, 'count' the numbers of
* rows to fetch.
* @return a DB_Result object or a DB_Error
*/
function db_query_range($query) {
global $db_handle, $queries;
......
......@@ -49,8 +49,8 @@ function menu_get_active_item() {
}
/**
* Returns the title of the active menu item.
*/
* Returns the title of the active menu item.
*/
function menu_get_active_title() {
global $_list;
......@@ -60,8 +60,8 @@ function menu_get_active_title() {
}
/**
* Returns the help associated with the active menu item.
*/
* Returns the help associated with the active menu item.
*/
function menu_get_active_help() {
$path = $_GET["q"];
$output = "";
......
This diff is collapsed.
This diff is collapsed.
......@@ -101,9 +101,11 @@ function block_admin_save($edit) {
/**
* update blocks db table with blocks currently exported by modules
*
* @param $order_by php <a href="http://www.php.net/manual/en/function.array-multisort.php">array_multisort()</a> style sort ordering, eg. "weight", SORT_ASC, SORT_STRING.
* @param $order_by php <a
* href="http://www.php.net/manual/en/function.array-multisort.php">array_multisort()</a>
* style sort ordering, eg. "weight", SORT_ASC, SORT_STRING.
*
* @return blocks currently exported by modules, sorted by $order_by
* @return blocks currently exported by modules, sorted by $order_by
*/
function _block_rehash($order_by = array("weight")) {
$result = db_query("SELECT * FROM {blocks} ");
......@@ -355,13 +357,13 @@ function block_user($type, &$edit, &$user) {
/**
* Return blocks available for current $user at $region.
*
* @param $region main|left|right
* @param $region main|left|right
*
* @return array of block objects, indexed with <i>module</i>_<i>delta</i>
* @return array of block objects, indexed with <i>module</i>_<i>delta</i>
*
* @see <a href="http://drupal.org/node/view/1042" target="_top">[feature]
* @see <a href="http://drupal.org/node/view/1042" target="_top">[feature]
* Generic template design difficult w/o block region "look-ahead"</a>
* @todo add a proper primary key (bid) to the blocks table so we don't have
* @todo add a proper primary key (bid) to the blocks table so we don't have
* to mess around with this <i>module</i>_<i>delta</i> construct. currently,
* "blocks" has no primary key defined (bad)!
*/
......
......@@ -101,9 +101,11 @@ function block_admin_save($edit) {
/**
* update blocks db table with blocks currently exported by modules
*
* @param $order_by php <a href="http://www.php.net/manual/en/function.array-multisort.php">array_multisort()</a> style sort ordering, eg. "weight", SORT_ASC, SORT_STRING.
* @param $order_by php <a
* href="http://www.php.net/manual/en/function.array-multisort.php">array_multisort()</a>
* style sort ordering, eg. "weight", SORT_ASC, SORT_STRING.
*
* @return blocks currently exported by modules, sorted by $order_by
* @return blocks currently exported by modules, sorted by $order_by
*/
function _block_rehash($order_by = array("weight")) {
$result = db_query("SELECT * FROM {blocks} ");
......@@ -355,13 +357,13 @@ function block_user($type, &$edit, &$user) {
/**
* Return blocks available for current $user at $region.
*
* @param $region main|left|right
* @param $region main|left|right
*
* @return array of block objects, indexed with <i>module</i>_<i>delta</i>
* @return array of block objects, indexed with <i>module</i>_<i>delta</i>
*
* @see <a href="http://drupal.org/node/view/1042" target="_top">[feature]
* @see <a href="http://drupal.org/node/view/1042" target="_top">[feature]
* Generic template design difficult w/o block region "look-ahead"</a>
* @todo add a proper primary key (bid) to the blocks table so we don't have
* @todo add a proper primary key (bid) to the blocks table so we don't have
* to mess around with this <i>module</i>_<i>delta</i> construct. currently,
* "blocks" has no primary key defined (bad)!
*/
......
......@@ -1531,8 +1531,9 @@ function comment_num_replies($pid) {
/**
* 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 to node)
* @param $nid node-id to count comments for
* @param $timestamp time to count from (defaults to time of last user access
* to node)
*/
function comment_num_new($nid, $timestamp = 0) {
global $user;
......
......@@ -1531,8 +1531,9 @@ function comment_num_replies($pid) {
/**
* 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 to node)
* @param $nid node-id to count comments for
* @param $timestamp time to count from (defaults to time of last user access
* to node)
*/
function comment_num_new($nid, $timestamp = 0) {
global $user;
......
......@@ -459,23 +459,23 @@ function forum_page() {
}
/**
@addtogroup themeable
@{
**/
* @addtogroup themeable
* @{
*/
/**
Format the forum body.
@param forums
@param topics
@param parents
@param tid
@param sortby
@param forum_per_page
@param offset
@return the output for the forum body.
**/
* Format the forum body.
*
* @param forums
* @param topics
* @param parents
* @param tid
* @param sortby
* @param forum_per_page
* @param offset
*
* @return the output for the forum body.
*/
function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_per_page, $offset) {
// forum list, topics list, topic browser and "add new topic" link
......@@ -519,14 +519,14 @@ 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.
**/
* Format the forum listing.
*
* @param forums
* @param parents
* @param tid
*
* @return output for the forum listing.
*/
function theme_forum_list($forums, $parents, $tid) {
global $user;
......@@ -582,16 +582,16 @@ function theme_forum_list($forums, $parents, $tid) {
}
/**
Format the topic listing.
@param tid
@param topics
@param sortby
@param forum_per_page
@param offset
@return output for the topic list.
**/
* Format the topic listing.
*
* @param tid
* @param topics
* @param sortby
* @param forum_per_page
* @param offset
*
* @return output for the topic list.
*/
function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page, $offset) {
global $id, $status, $user, $pager_total, $forum_topic_list_header;
......@@ -632,7 +632,7 @@ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page, $offset
return $output;
}
/** @} End of addtogroup themeable **/
/** @} End of addtogroup themeable */
function _forum_icon($new_posts, $num_posts = 0, $comment_mode = 0) {
......
......@@ -459,23 +459,23 @@ function forum_page() {
}
/**
@addtogroup themeable
@{
**/
* @addtogroup themeable
* @{
*/
/**
Format the forum body.
@param forums
@param topics
@param parents
@param tid
@param sortby
@param forum_per_page
@param offset
@return the output for the forum body.
**/
* Format the forum body.
*
* @param forums
* @param topics
* @param parents
* @param tid
* @param sortby
* @param forum_per_page
* @param offset
*
* @return the output for the forum body.
*/
function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_per_page, $offset) {
// forum list, topics list, topic browser and "add new topic" link
......@@ -519,14 +519,14 @@ 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.
**/
* Format the forum listing.
*
* @param forums
* @param parents
* @param tid
*
* @return output for the forum listing.
*/
function theme_forum_list($forums, $parents, $tid) {
global $user;
......@@ -582,16 +582,16 @@ function theme_forum_list($forums, $parents, $tid) {
}
/**
Format the topic listing.
@param tid
@param topics
@param sortby
@param forum_per_page
@param offset
@return output for the topic list.
**/
* Format the topic listing.
*
* @param tid
* @param topics
* @param sortby
* @param forum_per_page
* @param offset
*
* @return output for the topic list.
*/
function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page, $offset) {
global $id, $status, $user, $pager_total, $forum_topic_list_header;
......@@ -632,7 +632,7 @@ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page, $offset
return $output;
}
/** @} End of addtogroup themeable **/
/** @} End of addtogroup themeable */
function _forum_icon($new_posts, $num_posts = 0, $comment_mode = 0) {
......
......@@ -112,11 +112,13 @@ function node_last_viewed($nid) {
}
/**
* Determines whether the supplied timestamp is newer than the user's last view of a given node
* Determines whether the supplied timestamp is newer than the user's last view
* of a given node
*
* @param $nid node-id twhose history supplies the 'last viewed' timestamp
* @param $timestamp time which is compared against node's 'last veiwed' timestamp
*/
* @param $nid node-id twhose history supplies the 'last viewed' timestamp
* @param $timestamp time which is compared against node's 'last veiwed'
* timestamp
*/
function node_is_new($nid, $timestamp) {
global $user;
static $cache;
......
......@@ -112,11 +112,13 @@ function node_last_viewed($nid) {
}
/**
* Determines whether the supplied timestamp is newer than the user's last view of a given node
* Determines whether the supplied timestamp is newer than the user's last view
* of a given node
*
* @param $nid node-id twhose history supplies the 'last viewed' timestamp
* @param $timestamp time which is compared against node's 'last veiwed' timestamp
*/
* @param $nid node-id twhose history supplies the 'last viewed' timestamp
* @param $timestamp time which is compared against node's 'last veiwed'
* timestamp
*/
function node_is_new($nid, $timestamp) {
global $user;
static $cache;
......
......@@ -32,7 +32,7 @@ function search_perm() {
/**
* Return an array of links to be displayed
*
* @param $type The type of page requesting the link
* @param $type The type of page requesting the link
*
*/
function search_link($type) {
......@@ -99,11 +99,11 @@ function search_cron() {
*
* Search function called by each node that supports the indexed search.
*
* @param $search_array an array as returned from <i>module</i>_search
* of type array("keys" => ..., "type" => ..., "select" => ...)
* @see node_search for an explanation of array items
* @param $search_array an array as returned from <i>module</i>_search of type
* array("keys" => ..., "type" => ..., "select" => ...)
* @see node_search for an explanation of array items
*
* @return array of search results, each element being an array indexed with
* @return array of search results, each element being an array indexed with
* "count", "title", "link", "user" (name), "date", "keywords"
*/
function do_search($search_array) {
......@@ -216,9 +216,9 @@ function do_search($search_array) {
/**
* Update the search_index table
*
* @param $search_array an array as returned from <i>module</i>_update_index
* @param $search_array an array as returned from <i>module</i>_update_index
* of type array("last_update" => ..., "node_type" => ..., "select" => ...)
* @see node_update_index for an explanation of array items
* @see node_update_index for an explanation of array items
*/
function update_index($search_array) {
$last_update = variable_get($search_array["last_update"], 1);
......@@ -327,8 +327,8 @@ function search_invalidate() {
/**
* Save the values entered by the administrator for the search module
*
* @param $edit An array of fields as setup via calling form_textfield,
* form_textarea etc
* @param $edit An array of fields as setup via calling form_textfield,
* form_textarea etc
*/
function search_save($edit) {
variable_set("minimum_word_size", $edit["minimum_word_size"]);
......
......@@ -32,7 +32,7 @@ function search_perm() {
/**
* Return an array of links to be displayed
*
* @param $type The type of page requesting the link
* @param $type The type of page requesting the link
*
*/
function search_link($type) {
......@@ -99,11 +99,11 @@ function search_cron() {
*
* Search function called by each node that supports the indexed search.
*
* @param $search_array an array as returned from <i>module</i>_search
* of type array("keys" => ..., "type" => ..., "select" => ...)
* @see node_search for an explanation of array items
* @param $search_array an array as returned from <i>module</i>_search of type
* array("keys" => ..., "type" => ..., "select" => ...)
* @see node_search for an explanation of array items
*
* @return array of search results, each element being an array indexed with
* @return array of search results, each element being an array indexed with
* "count", "title", "link", "user" (name), "date", "keywords"
*/
function do_search($search_array) {
......@@ -216,9 +216,9 @@ function do_search($search_array) {
/**
* Update the search_index table
*
* @param $search_array an array as returned from <i>module</i>_update_index
* @param $search_array an array as returned from <i>module</i>_update_index
* of type array("last_update" => ..., "node_type" => ..., "select" => ...)
* @see node_update_index for an explanation of array items
* @see node_update_index for an explanation of array items
*/
function update_index($search_array) {
$last_update = variable_get($search_array["last_update"], 1);
......@@ -327,8 +327,8 @@ function search_invalidate() {
/**
* Save the values entered by the administrator for the search module
*
* @param $edit An array of fields as setup via calling form_textfield,
* form_textarea etc
* @param $edit An array of fields as setup via calling form_textfield,
* form_textarea etc
*/
function search_save($edit) {
variable_set("minimum_word_size", $edit["minimum_word_size"]);
......
......@@ -540,12 +540,11 @@ function _taxonomy_term_children($tid) {
}
/**
* Try to map a string to existing vocabularies.
* Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping.
* Try to map a string to existing vocabularies. Provide case insensitive and
* trimmed map so as to maximize likelihood of successful mapping.
*
* @param $name Name of the vocabulary to search
* @return array of matching vocabularies, as objects
* @param $name Name of the vocabulary to search
* @return array of matching vocabularies, as objects
*/
function taxonomy_get_vocabulary_by_name($name) {
// LOWER is ANSI SQL-92
......@@ -559,12 +558,11 @@ function taxonomy_get_vocabulary_by_name($name) {
}
/**
* Try to map a string to existing terms
* Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping.
* Try to map a string to existing terms Provide case insensitive and trimmed
* map so as to maximize likelihood of successful mapping.
*
* @param name Name of the term to search
* @return rray of matching terms, as objects
* @param name Name of the term to search
* @return rray of matching terms, as objects
*/
function taxonomy_get_term_by_name($name) {
// LOWER is ANSI SQL-92
......
......@@ -540,12 +540,11 @@ function _taxonomy_term_children($tid) {
}
/**
* Try to map a string to existing vocabularies.
* Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping.
* Try to map a string to existing vocabularies. Provide case insensitive and
* trimmed map so as to maximize likelihood of successful mapping.
*
* @param $name Name of the vocabulary to search
* @return array of matching vocabularies, as objects
* @param $name Name of the vocabulary to search
* @return array of matching vocabularies, as objects
*/
function taxonomy_get_vocabulary_by_name($name) {
// LOWER is ANSI SQL-92
......@@ -559,12 +558,11 @@ function taxonomy_get_vocabulary_by_name($name) {
}
/**
* Try to map a string to existing terms
* Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping.
* Try to map a string to existing terms Provide case insensitive and trimmed
* map so as to maximize likelihood of successful mapping.
*
* @param name Name of the term to search
* @return rray of matching terms, as objects
* @param name Name of the term to search
* @return rray of matching terms, as objects
*/
function taxonomy_get_term_by_name($name) {
// LOWER is ANSI SQL-92
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment