Commit 06045ff7 authored by Dries's avatar Dries

Patch by Ax to fixe and improve to the core doxygen PHPdoc:

  * fixes all doxygen warnings [#]_ in the current code base
    + changes @param style from phpDocumentor (@param type $var desc) to doxygen (@param $var desc)
    + documents all undocumented parameters
    + escapes / fixes html warnings
    + fixes @defgroup in theme.inc
  * adds more groupings [#]_
    + drupal_{set|get}_title, drupal_{set|get}_breadcrumb
    + pager.inc: pager_api (pager_query(), pager_display()), pager pieces
  * adds a new group "themeable" which contains all themeable functions.
parent af5bc7cd
...@@ -14,9 +14,12 @@ Drupal x.x.x, xxxx-xx-xx ...@@ -14,9 +14,12 @@ Drupal x.x.x, xxxx-xx-xx
- usability: - usability:
* added breadcrumb navigation to all pages. * added breadcrumb navigation to all pages.
* made it possible to add context-sensitive help to all pages. * made it possible to add context-sensitive help to all pages.
* grouped form elements using '<fieldset>' and '<legend>' tags.
* replaced drop-down menus by radio buttons where appropriate. * replaced drop-down menus by radio buttons where appropriate.
* removed the 'magic_quotes_gpc = 0' requirement. * removed the 'magic_quotes_gpc = 0' requirement.
- accessibility:
* made themes degrade gracefully in absence of CSS.
* grouped form elements using '<fieldset>' and '<legend>' tags.
* added '<label>' tags to form elements.
- documentation: - documentation:
* added PHPDoc/Doxygen comments. * added PHPDoc/Doxygen comments.
......
...@@ -2,7 +2,9 @@ ...@@ -2,7 +2,9 @@
// $Id$ // $Id$
/** /**
* @name drupal_title
* Functions to get and set the title of the current page. * Functions to get and set the title of the current page.
* @{
*/ */
function drupal_set_title($title = NULL) { function drupal_set_title($title = NULL) {
static $stored_title; static $stored_title;
...@@ -22,12 +24,14 @@ function drupal_get_title() { ...@@ -22,12 +24,14 @@ function drupal_get_title() {
return $title; return $title;
} }
// @}
/** /**
* @name drupal_breadcrumb
* Functions to get and set the breadcrumb trail of the current page. The * Functions to get and set the breadcrumb trail of the current page. The
* breadcrumb trail is represented as an array of links, starting with * breadcrumb trail is represented as an array of links, starting with
* "home" and proceeding up to but not including the current page. * "home" and proceeding up to but not including the current page.
* @{
*/ */
function drupal_set_breadcrumb($breadcrumb = NULL) { function drupal_set_breadcrumb($breadcrumb = NULL) {
static $stored_breadcrumb; static $stored_breadcrumb;
...@@ -48,7 +52,7 @@ function drupal_get_breadcrumb() { ...@@ -48,7 +52,7 @@ function drupal_get_breadcrumb() {
return $breadcrumb; return $breadcrumb;
} }
// @}
/** /**
* Build the alias/path array * Build the alias/path array
...@@ -249,9 +253,9 @@ function valid_url($url) { ...@@ -249,9 +253,9 @@ function valid_url($url) {
/** /**
* Format a single result entry of a search query: * Format a single result entry of a search query:
* *
* @param $item a single search result as returned by <module>_search of type * @param $item a single search result as returned by <i>module</i>_search of
* array("count" => ..., "link" => ..., "title" => ..., * type array("count" => ..., "link" => ..., "title" => ..., "user" => ...,
* "user" => ..., "date" => ..., "keywords" => ...) * "date" => ..., "keywords" => ...)
* @param $type module type of this item * @param $type module type of this item
*/ */
function search_item($item, $type) { function search_item($item, $type) {
...@@ -344,7 +348,7 @@ function search_data($keys = NULL) { ...@@ -344,7 +348,7 @@ function search_data($keys = NULL) {
* @param $type If set, search only nodes of this type. * @param $type If set, search only nodes of this type.
* Otherwise, search all types. * Otherwise, search all types.
* @param $action Form action. Defaults to 'site.com/search'. * @param $action Form action. Defaults to 'site.com/search'.
* @param $query Query string. Defaults to global $keys. * @param $keys Query string. Defaults to global $keys.
* @param $options != 0: Render additional form fields/text * @param $options != 0: Render additional form fields/text
* ("Restrict search to", help text, etc). * ("Restrict search to", help text, etc).
*/ */
......
...@@ -21,6 +21,12 @@ function db_connect($url) { ...@@ -21,6 +21,12 @@ 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.
*/
function db_query($query) { function db_query($query) {
$args = func_get_args(); $args = func_get_args();
...@@ -142,9 +148,8 @@ function db_affected_rows() { ...@@ -142,9 +148,8 @@ function db_affected_rows() {
/** /**
* Runs a LIMIT query in the database. * Runs a LIMIT query in the database.
* *
* @param mixed $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. * @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 resource a MySQL result or FALSE if the query was not executed correctly. * @return a MySQL result or FALSE if the query was not executed correctly.
* @access public
*/ */
function db_query_range($query) { function db_query_range($query) {
$args = func_get_args(); $args = func_get_args();
......
...@@ -18,9 +18,8 @@ function db_connect($url) { ...@@ -18,9 +18,8 @@ function db_connect($url) {
/** /**
* Runs a query in the database. * Runs a query in the database.
* *
* @param $query SQL query * @param $query SQL query, followed by a variable number of arguments which are substituted into query by sprintf.
* @param $type module type of this item * @return a DB_Result object or a DB_Error
* @return sql result resource
*/ */
function db_query($query) { function db_query($query) {
...@@ -146,9 +145,8 @@ function db_affected_rows() { ...@@ -146,9 +145,8 @@ function db_affected_rows() {
/** /**
* Runs a LIMIT query in the database. * Runs a LIMIT query in the database.
* *
* @param mixed $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. * @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 mixed a DB_Result object or a DB_Error * @return a DB_Result object or a DB_Error
* @access public
*/ */
function db_query_range($query) { function db_query_range($query) {
global $db_handle, $queries; global $db_handle, $queries;
......
This diff is collapsed.
...@@ -128,29 +128,6 @@ function theme_node($node, $main) { ...@@ -128,29 +128,6 @@ function theme_node($node, $main) {
return $output; return $output;
} }
function _theme_table_cell($cell, $header = 0) {
if (is_array($cell)) {
$data = $cell["data"];
foreach ($cell as $key => $value) {
if ($key != "data") {
$attributes .= " $key=\"$value\"";
}
}
}
else {
$data = $cell;
}
if ($header) {
$output = "<th$attributes>$data</th>";
}
else {
$output = "<td$attributes>$data</td>";
}
return $output;
}
/** /**
Returns themed table. Returns themed table.
...@@ -331,7 +308,7 @@ function theme_head($main = 0) { ...@@ -331,7 +308,7 @@ function theme_head($main = 0) {
/** /**
Execute hook _footer() which is run at the end of the page right Execute hook _footer() which is run at the end of the page right
before the </body> tag. before the \</body> tag.
@param $main (optional) @param $main (optional)
...@@ -381,109 +358,28 @@ function theme_blocks($region) { ...@@ -381,109 +358,28 @@ function theme_blocks($region) {
} }
return $output; return $output;
} }
/** @} End of defgroup themeable **/
/** function _theme_table_cell($cell, $header = 0) {
Hook Help - returns theme specific help and information. if (is_array($cell)) {
$data = $cell["data"];
@param section defines the \a section of the help to be returned. foreach ($cell as $key => $value) {
if ($key != "data") {
@return a string containing the help output. $attributes .= " $key=\"$value\"";
**/
function theme_help($section) {
$ouptout = "";
switch ($section) {
case 'admin/system/themes#description':
$output = t("The base theme");
break;
}
return $output;
}
/**
Provides a list of currently available themes.
@param $refresh
@return an array of the currently available themes.
**/
function list_themes($refresh = 0) {
static $list;
if ($refresh) {
unset($list);
}
if (!$list) {
$list = array();
$result = db_query("SELECT * FROM {system} where type = 'theme' AND status = '1' ORDER BY name");
while ($theme = db_fetch_object($result)) {
if (file_exists($theme->filename)) {
$list[$theme->name] = $theme;
} }
} }
} }
else {
return $list; $data = $cell;
}
/**
Initialized the theme system.
@return the name of the currently selected theme.
**/
function init_theme() {
global $user;
$themes = list_themes();
$name = $user->theme ? $user->theme : variable_get("theme_default", 0);
$theme->path = "";
$theme->name = "";
if (is_object($themes[$name])) {
include_once($themes[$name]->filename);
$theme->path = dirname($themes[$name]->filename);
$theme->name = $name;
} }
return $theme; if ($header) {
} $output = "<th$attributes>$data</th>";
/**
Returns the path to the currently selected theme.
@return the path to the the currently selected theme.
**/
function path_to_theme() {
global $theme;
return $theme->path;
}
/**
External interface of the theme system to all other modules, and core files.
All requests for themed functions must go through this function. It examines
the request and routes it to the appropriate theme function. If the current
theme does not implement the requested function, then the base theme function
is called.
Example: \verbatim $header_text = theme("header"); \endverbatim
@return the path to the the currently selected theme.
**/
function theme() {
global $theme;
$args = func_get_args();
$function = array_shift($args);
if (($theme->name != "") && (function_exists($theme->name ."_". $function))) {
return call_user_func_array($theme->name ."_". $function, $args);
} }
elseif (function_exists("theme_". $function)){ else {
return call_user_func_array("theme_". $function, $args); $output = "<td$attributes>$data</td>";
} }
}
/** @} End of defgroup theme_system **/ return $output;
}
?> ?>
...@@ -103,9 +103,9 @@ function block_admin_save($edit) { ...@@ -103,9 +103,9 @@ function block_admin_save($edit) {
/** /**
* update blocks db table with blocks currently exported by modules * update blocks db table with blocks currently exported by modules
* *
* @param array $order_by php array_multisort() style sort ordering, eg. "weight", SORT_ASC, SORT_STRING. see {@link http://www.php.net/manual/en/function.array-multisort.php} * @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 array blocks currently exported by modules, sorted by $order_by *
* @access private * @return blocks currently exported by modules, sorted by $order_by
*/ */
function _block_rehash($order_by = array("weight")) { function _block_rehash($order_by = array("weight")) {
$result = db_query("SELECT * FROM {blocks} "); $result = db_query("SELECT * FROM {blocks} ");
......
...@@ -103,9 +103,9 @@ function block_admin_save($edit) { ...@@ -103,9 +103,9 @@ function block_admin_save($edit) {
/** /**
* update blocks db table with blocks currently exported by modules * update blocks db table with blocks currently exported by modules
* *
* @param array $order_by php array_multisort() style sort ordering, eg. "weight", SORT_ASC, SORT_STRING. see {@link http://www.php.net/manual/en/function.array-multisort.php} * @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 array blocks currently exported by modules, sorted by $order_by *
* @access private * @return blocks currently exported by modules, sorted by $order_by
*/ */
function _block_rehash($order_by = array("weight")) { function _block_rehash($order_by = array("weight")) {
$result = db_query("SELECT * FROM {blocks} "); $result = db_query("SELECT * FROM {blocks} ");
......
...@@ -64,7 +64,6 @@ function search_settings() { ...@@ -64,7 +64,6 @@ function search_settings() {
/** /**
* search engine administration actions * search engine administration actions
*
*/ */
function search_admin() { function search_admin() {
$op = $_POST["op"]; $op = $_POST["op"];
...@@ -90,8 +89,7 @@ function search_admin() { ...@@ -90,8 +89,7 @@ function search_admin() {
/** /**
* perform a regularly run action across all modules that have the * perform a regularly run action across all modules that have the
* <module>_update_index function in them. * <i>module</i>_update_index function in them.
*
*/ */
function search_cron() { function search_cron() {
foreach (module_list() as $module) { foreach (module_list() as $module) {
...@@ -105,15 +103,16 @@ function search_cron() { ...@@ -105,15 +103,16 @@ function search_cron() {
} }
/** /**
* Perform a search on a word(s) * Perform a search on a word(s).
*
* Search function called by each node that supports the indexed search.
* *
* 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 <module>_search * @return array of search results, each element being an array indexed with
* of type array("keys" => ..., * "count", "title", "link", "user" (name), "date", "keywords"
* "type" => ..., "select" => ...)
* see node_search in node.module for an
* explanation of array items
*/ */
function do_search($search_array) { function do_search($search_array) {
...@@ -225,11 +224,9 @@ function do_search($search_array) { ...@@ -225,11 +224,9 @@ function do_search($search_array) {
/** /**
* Update the search_index table * Update the search_index table
* *
* @param $search_array an array as returned from <module>_update_index * @param $search_array an array as returned from <i>module</i>_update_index
* of type array("last_update" => ..., * of type array("last_update" => ..., "node_type" => ..., "select" => ...)
* "node_type" => ..., "select" => ...) * @see node_update_index for an explanation of array items
* see node_update_index in node.module for an
* explanation of array items
*/ */
function update_index($search_array) { function update_index($search_array) {
$last_update = variable_get($search_array["last_update"], 1); $last_update = variable_get($search_array["last_update"], 1);
......
...@@ -64,7 +64,6 @@ function search_settings() { ...@@ -64,7 +64,6 @@ function search_settings() {
/** /**
* search engine administration actions * search engine administration actions
*
*/ */
function search_admin() { function search_admin() {
$op = $_POST["op"]; $op = $_POST["op"];
...@@ -90,8 +89,7 @@ function search_admin() { ...@@ -90,8 +89,7 @@ function search_admin() {
/** /**
* perform a regularly run action across all modules that have the * perform a regularly run action across all modules that have the
* <module>_update_index function in them. * <i>module</i>_update_index function in them.
*
*/ */
function search_cron() { function search_cron() {
foreach (module_list() as $module) { foreach (module_list() as $module) {
...@@ -105,15 +103,16 @@ function search_cron() { ...@@ -105,15 +103,16 @@ function search_cron() {
} }
/** /**
* Perform a search on a word(s) * Perform a search on a word(s).
*
* Search function called by each node that supports the indexed search.
* *
* 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 <module>_search * @return array of search results, each element being an array indexed with
* of type array("keys" => ..., * "count", "title", "link", "user" (name), "date", "keywords"
* "type" => ..., "select" => ...)
* see node_search in node.module for an
* explanation of array items
*/ */
function do_search($search_array) { function do_search($search_array) {
...@@ -225,11 +224,9 @@ function do_search($search_array) { ...@@ -225,11 +224,9 @@ function do_search($search_array) {
/** /**
* Update the search_index table * Update the search_index table
* *
* @param $search_array an array as returned from <module>_update_index * @param $search_array an array as returned from <i>module</i>_update_index
* of type array("last_update" => ..., * of type array("last_update" => ..., "node_type" => ..., "select" => ...)
* "node_type" => ..., "select" => ...) * @see node_update_index for an explanation of array items
* see node_update_index in node.module for an
* explanation of array items
*/ */
function update_index($search_array) { function update_index($search_array) {
$last_update = variable_get($search_array["last_update"], 1); $last_update = variable_get($search_array["last_update"], 1);
......
...@@ -538,12 +538,12 @@ function _taxonomy_term_children($tid) { ...@@ -538,12 +538,12 @@ function _taxonomy_term_children($tid) {
} }
/** /**
* Try to map a string to existing vocabularies * Try to map a string to existing vocabularies.
* Provide case insensitive and trimmed map so as to * Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping. * maximize likelihood of successful mapping.
* *
* @param string $name Name of the vocabulary to search * @param $name Name of the vocabulary to search
* @return array array of matching vocabularies, as objects * @return array of matching vocabularies, as objects
*/ */
function taxonomy_get_vocabulary_by_name($name) { function taxonomy_get_vocabulary_by_name($name) {
// LOWER is ANSI SQL-92 // LOWER is ANSI SQL-92
...@@ -561,8 +561,8 @@ function taxonomy_get_vocabulary_by_name($name) { ...@@ -561,8 +561,8 @@ function taxonomy_get_vocabulary_by_name($name) {
* Provide case insensitive and trimmed map so as to * Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping. * maximize likelihood of successful mapping.
* *
* @param string $name Name of the term to search * @param name Name of the term to search
* @return array array of matching terms, as objects * @return rray of matching terms, as objects
*/ */
function taxonomy_get_term_by_name($name) { function taxonomy_get_term_by_name($name) {
// LOWER is ANSI SQL-92 // LOWER is ANSI SQL-92
......
...@@ -538,12 +538,12 @@ function _taxonomy_term_children($tid) { ...@@ -538,12 +538,12 @@ function _taxonomy_term_children($tid) {
} }
/** /**
* Try to map a string to existing vocabularies * Try to map a string to existing vocabularies.
* Provide case insensitive and trimmed map so as to * Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping. * maximize likelihood of successful mapping.
* *
* @param string $name Name of the vocabulary to search * @param $name Name of the vocabulary to search
* @return array array of matching vocabularies, as objects * @return array of matching vocabularies, as objects
*/ */
function taxonomy_get_vocabulary_by_name($name) { function taxonomy_get_vocabulary_by_name($name) {
// LOWER is ANSI SQL-92 // LOWER is ANSI SQL-92
...@@ -561,8 +561,8 @@ function taxonomy_get_vocabulary_by_name($name) { ...@@ -561,8 +561,8 @@ function taxonomy_get_vocabulary_by_name($name) {
* Provide case insensitive and trimmed map so as to * Provide case insensitive and trimmed map so as to
* maximize likelihood of successful mapping. * maximize likelihood of successful mapping.
* *
* @param string $name Name of the term to search * @param name Name of the term to search
* @return array array of matching terms, as objects * @return rray of matching terms, as objects
*/ */
function taxonomy_get_term_by_name($name) { function taxonomy_get_term_by_name($name) {
// LOWER is ANSI SQL-92 // 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