From c3d87db6a0f7521ca411b772af8ca19c8ef740c4 Mon Sep 17 00:00:00 2001 From: Peter Westwood Date: Sat, 6 Sep 2008 06:38:26 +0000 Subject: [PATCH] General Template function phpdoc updates. See #5640 props jacobsantos. git-svn-id: https://develop.svn.wordpress.org/trunk@8835 602fd350-edb4-49c9-b593-d223f7449a82 --- wp-includes/general-template.php | 276 +++++++++++++++++-------------- 1 file changed, 155 insertions(+), 121 deletions(-) diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index ee76bbc1a5..973fd5ac67 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -9,13 +9,18 @@ /** * Load header template. * - * Includes the header template for a theme or if a name is specified then a specialised header will be included. - * If the theme contains no header.php file then the header from the default theme will be included. + * Includes the header template for a theme or if a name is specified then a + * specialised header will be included. If the theme contains no header.php file + * then the header from the default theme will be included. + * + * For the parameter, if the file is called "header-special.php" then specify + * "special". * * @uses locate_template() * @since 1.5.0 * @uses do_action() Calls 'get_header' action. - * @param $name String The name of the specialised header. If the file is called "header-special.php" then specify "special". + * + * @param string $name The name of the specialised header. */ function get_header( $name = null ) { do_action( 'get_header' ); @@ -33,13 +38,18 @@ function get_header( $name = null ) { /** * Load footer template. * - * Includes the footer template for a theme or if a name is specified then a specialised footer will be included. - * If the theme contains no footer.php file then the footer from the default theme will be included. + * Includes the footer template for a theme or if a name is specified then a + * specialised footer will be included. If the theme contains no footer.php file + * then the footer from the default theme will be included. + * + * For the parameter, if the file is called "footer-special.php" then specify + * "special". * * @uses locate_template() * @since 1.5.0 * @uses do_action() Calls 'get_footer' action. - * @param $name String The name of the specialised footer. If the file is called "footer-special.php" then specify "special". + * + * @param string $name The name of the specialised footer. */ function get_footer( $name = null ) { do_action( 'get_footer' ); @@ -57,13 +67,18 @@ function get_footer( $name = null ) { /** * Load sidebar template. * - * Includes the sidebar template for a theme or if a name is specified then a specialised sidebar will be included. - * If the theme contains no sidebar.php file then the sidebar from the default theme will be included. + * Includes the sidebar template for a theme or if a name is specified then a + * specialised sidebar will be included. If the theme contains no sidebar.php + * file then the sidebar from the default theme will be included. + * + * For the parameter, if the file is called "sidebar-special.php" then specify + * "special". * * @uses locate_template() * @since 1.5.0 * @uses do_action() Calls 'get_sidebar' action. - * @param $name String The name of the specialised sidebar. If the file is called "sidebar-special.php" then specify "special". + * + * @param string $name The name of the specialised sidebar. */ function get_sidebar( $name = null ) { do_action( 'get_sidebar' ); @@ -79,12 +94,13 @@ function get_sidebar( $name = null ) { } /** - * Echo the Log In/Out link + * Display the Log In/Out link. * - * Echos out a link which allows the user to navigate to the Login page to login or logout depending on whether or not they are currently logged in. + * Displays a link, which allows the user to navigate to the Login page to login + * or logout depending on whether or not they are currently logged in. * * @since 1.5.0 - * @uses apply_filters() + * @uses apply_filters() Calls 'loginout' hook on HTML link content. */ function wp_loginout() { if ( ! is_user_logged_in() ) @@ -96,15 +112,16 @@ function wp_loginout() { } /** -* Echo the Registration or Admin link + * Display the Registration or Admin link. * - * Echos out a link which allows the user to navigate to the registration page if not logged in and registration is enabled or to the dashboard if logged in. + * Display a link which allows the user to navigate to the registration page if + * not logged in and registration is enabled or to the dashboard if logged in. * * @since 1.5.0 - * @uses apply_filters() + * @uses apply_filters() Calls 'register' hook on register / admin link content. * - * @param String $before Text to output before the link (defaults to
  • ). - * @param String $after Text to output after the link (defaults to
    • ). + * @param string $before Text to output before the link (defaults to
  • ). + * @param string $after Text to output after the link (defaults to
    • ). */ function wp_register( $before = '
  • ', $after = '
    • ' ) { @@ -127,7 +144,7 @@ function wp_register( $before = '
  • ', $after = '
    • ' ) { * but one purpose might have been to allow for theme switching. * * @since 1.5.0 - * @link http://trac.wordpress.org/ticket/1458 Explaination of 'wp_meta' action. + * @link http://trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action. * @uses do_action() Calls 'wp_meta' hook. */ function wp_meta() { @@ -135,33 +152,45 @@ function wp_meta() { } /** - * bloginfo() - {@internal Missing Short Description}} - * - * {@internal Missing Long Description}} + * Display information about the blog. * + * @see get_bloginfo() For possible values for the parameter. * @since 0.71 * - * @param unknown_type $show + * @param string $show What to display. */ function bloginfo($show='') { echo get_bloginfo($show, 'display'); } /** - * get_bloginfo() - {@internal Missing Short Description}} + * Retrieve information about the blog. * - * {@internal Missing Long Description}} + * Some show parameter values are deprecated and will be removed in future + * versions. Care should be taken to check the function contents and know what + * the deprecated blog info options are. Options without "// DEPRECATED" are + * the preferred and recommended ways to get the information. * - * Note: some of these values are DEPRECATED. Meaning they could be - * taken out at any time and shouldn't be relied upon. Options - * without "// DEPRECATED" are the preferred and recommended ways - * to get the information. + * The possible values for the 'show' parameter are listed below. + *
      + *
    1. url - Blog URI to homepage.
      2. + *
    2. wpurl - Blog URI path to WordPress.
      3. + *
    3. description - Secondary title
      4. + *
    + * + * The feed URL options can be retrieved from 'rdf_url' (RSS 0.91), + * 'rss_url' (RSS 1.0), 'rss2_url' (RSS 2.0), or 'atom_url' (Atom feed). The + * comment feeds can be retrieved from the 'comments_atom_url' (Atom comment + * feed) or 'comments_rss2_url' (RSS 2.0 comment feed). + * + * There are many other options and you should check the function contents: + * {@source 32 37} * * @since 0.71 * - * @param unknown_type $show - * @param unknown_type $filter - * @return unknown + * @param string $show Blog info to retrieve. + * @param string $filter How to filter what is retrieved. + * @return string Mostly string values, might be empty. */ function get_bloginfo($show = '', $filter = 'raw') { @@ -253,7 +282,7 @@ function get_bloginfo($show = '', $filter = 'raw') { } /** - * wp_title() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -369,7 +398,7 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { } /** - * single_post_title() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -399,7 +428,7 @@ function single_post_title($prefix = '', $display = true) { } /** - * single_cat_title() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -425,7 +454,7 @@ function single_cat_title($prefix = '', $display = true ) { } /** - * single_tag_title() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -456,7 +485,7 @@ function single_tag_title($prefix = '', $display = true ) { } /** - * single_month_title() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -492,7 +521,7 @@ function single_month_title($prefix = '', $display = true ) { } /** - * get_archives_link() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -527,7 +556,7 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after = } /** - * wp_get_archives() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -701,15 +730,15 @@ function wp_get_archives($args = '') { } /** - * calendar_week_mod() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * * @since 1.5.0 * @usedby get_calendar() * - * @param unknown_type $num - * @return unknown + * @param int $num Number of day. + * @return int */ function calendar_week_mod($num) { $base = 7; @@ -717,7 +746,7 @@ function calendar_week_mod($num) { } /** - * get_calendar() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -933,7 +962,7 @@ add_action( 'update_option_gmt_offset', 'delete_get_calendar_cache' ); add_action( 'update_option_start_of_week', 'delete_get_calendar_cache' ); /** - * allowed_tags() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -960,7 +989,7 @@ function allowed_tags() { /***** Date/Time tags *****/ /** - * Outputs the date in iso8601 format for xml files, + * Outputs the date in iso8601 format for xml files. * * @since 1.0.0 */ @@ -970,17 +999,18 @@ function the_date_xml() { } /** - * Echos or Returns the date the post was written. + * Display or Retrieve the date the post was written. * - * Will only output the date if the current post's date is different from the previous one output. + * Will only output the date if the current post's date is different from the + * previous one output. * * @since 0.71 * - * @param string $d php date format defaults to the date_format option if not specified. - * @param string $before output before the date. - * @param string $after output after the date. - * @param bool $echo Whether to echo the date or return it. - * @return unknown + * @param string $d Optional. PHP date format defaults to the date_format option if not specified. + * @param string $before Optional. Output before the date. + * @param string $after Optional. Output after the date. + * @param bool $echo Optional, default is display. Whether to echo the date or return it. + * @return string|null Null if displaying, string if retrieving. */ function the_date($d='', $before='', $after='', $echo = true) { global $post, $day, $previousday; @@ -1002,11 +1032,11 @@ function the_date($d='', $before='', $after='', $echo = true) { } /** - * Outputs the date on which the post was last modified. + * Display the date on which the post was last modified. * * @since 2.1.0 * - * @param string $d php date format. + * @param string $d Optional. PHP date format. * @return string */ function the_modified_date($d = '') { @@ -1014,11 +1044,11 @@ function the_modified_date($d = '') { } /** - * Returns the date on which the post was last modified. + * Retrieve the date on which the post was last modified. * * @since 2.1.0 * - * @param string $d php date format. Defaults to the "date_format" option + * @param string $d Optional. PHP date format. Defaults to the "date_format" option * @return string */ function get_the_modified_date($d = '') { @@ -1030,7 +1060,7 @@ function get_the_modified_date($d = '') { } /** - * Output the time at which the post was written. + * Display the time at which the post was written. * * @since 0.71 * @@ -1041,7 +1071,7 @@ function the_time( $d = '' ) { } /** - * Returns the time at which the post was written. + * Retrieve the time at which the post was written. * * @since 1.5.0 * @@ -1057,7 +1087,7 @@ function get_the_time( $d = '' ) { } /** - * Returns the time at which the post was written + * Retrieve the time at which the post was written. * * @since 2.0.0 * @@ -1077,20 +1107,18 @@ function get_post_time( $d = 'U', $gmt = false ) { // returns timestamp } /** - * the_modified_time() - {@internal Missing Short Description}} - * - * {@internal Missing Long Description}} + * Display the time at which the post was last modified. * * @since 2.0.0 * - * @param unknown_type $d + * @param string $d Either 'G', 'U', or php date format defaults to the value specified in the time_format option. */ function the_modified_time($d = '') { echo apply_filters('the_modified_time', get_the_modified_time($d), $d); } /** - * Returns the time at which the post was last modified. + * Retrieve the time at which the post was last modified. * * @since 2.0.0 * @@ -1106,15 +1134,15 @@ function get_the_modified_time($d = '') { } /** - * Returns the time at which the post was last modified. + * Retrieve the time at which the post was last modified. * * @since 2.0.0 * * @param string $d Either 'G', 'U', or php date format. * @param bool $gmt Whether of not to return the gmt time. - * @return string + * @return string Returns timestamp */ -function get_post_modified_time( $d = 'U', $gmt = false ) { // returns timestamp +function get_post_modified_time( $d = 'U', $gmt = false ) { global $post; if ( $gmt ) @@ -1127,7 +1155,7 @@ function get_post_modified_time( $d = 'U', $gmt = false ) { // returns timestamp } /** - * Outputs the weekday on which the post was written. + * Display the weekday on which the post was written. * * @since 0.71 * @uses $wp_locale @@ -1141,9 +1169,10 @@ function the_weekday() { } /** - * Outputs the weekday on which the post was written. + * Display the weekday on which the post was written. * - * Will only output the weekday if the current post's weekday is different from the previous one output. + * Will only output the weekday if the current post's weekday is different from + * the previous one output. * * @since 0.71 * @@ -1167,7 +1196,7 @@ function the_weekday_date($before='',$after='') { * Fire the wp_head action * * @since 1.2.0 - * @uses do_action() + * @uses do_action() Calls 'wp_head' hook. */ function wp_head() { do_action('wp_head'); @@ -1177,14 +1206,14 @@ function wp_head() { * Fire the wp_footer action * * @since 1.5.1 - * @uses do_action() + * @uses do_action() Calls 'wp_footer' hook. */ function wp_footer() { do_action('wp_footer'); } /** - * Outputs the link to the Really Simple Discovery service endpoint. + * Display the link to the Really Simple Discovery service endpoint. * * @link http://archipelago.phrasewise.com/rsd * @since 2.0.0 @@ -1194,7 +1223,7 @@ function rsd_link() { } /** - * Outputs the link to the Windows Live Writer manifest file. + * Display the link to the Windows Live Writer manifest file. * * @link http://msdn.microsoft.com/en-us/library/bb463265.aspx * @since 2.3.1 @@ -1205,9 +1234,10 @@ function wlwmanifest_link() { } /** - * Outputs a noindex meta tag if required by the blog configuration. + * Display a noindex meta tag if required by the blog configuration. * - * If a blog is marked as not being public then the noindex meta tag will be ouput to tell web robots not to index the page content. + * If a blog is marked as not being public then the noindex meta tag will be + * output to tell web robots not to index the page content. * * @since 2.1.0 */ @@ -1236,7 +1266,8 @@ function rich_edit_exists() { /** * Whether or not the user should have a WYSIWIG editor. * - * Checks that the user requires a WYSIWIG editor and that the editor is supported in the users browser. + * Checks that the user requires a WYSIWIG editor and that the editor is + * supported in the users browser. * * @since 2.0.0 * @@ -1260,9 +1291,10 @@ function user_can_richedit() { } /** - * Find out which editor should be displayed by default + * Find out which editor should be displayed by default. * - * Works out which of the two editors to display as the current editor for a user. + * Works out which of the two editors to display as the current editor for a + * user. * * @since 2.5.0 * @@ -1278,7 +1310,7 @@ function wp_default_editor() { } /** - * the_editor() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -1355,7 +1387,7 @@ function the_editor($content, $id = 'content', $prev_id = 'title', $media_button } /** - * Returns the contents of the search query variable 's' + * Retrieve the contents of the search WordPress query variable. * * @since 2.3.0 * @@ -1366,22 +1398,23 @@ function get_search_query() { } /** - * Outputs the contents of the search query variable 's' + * Display the contents of the search query variable. * - * The search query string is paseed through attribute_escape to ensure that it is safe for placing in an html attribute + * The search query string is passed through {@link attribute_escape()} + * to ensure that it is safe for placing in an html attribute. * * @uses attribute_escape * @since 2.1.0 - * */ function the_search_query() { echo attribute_escape( apply_filters( 'the_search_query', get_search_query() ) ); } /** - * Outputs the language attributes for the html tag. + * Display the language attributes for the html tag. * - * Builds up a set of html attributes containing the text direction and language information for the page. + * Builds up a set of html attributes containing the text direction and language + * information for the page. * * @since 2.1.0 * @@ -1408,7 +1441,7 @@ function language_attributes($doctype = 'html') { } /** - * paginate_links() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * @@ -1498,20 +1531,20 @@ function paginate_links( $args = '' ) { } /** - * Registers a admin colour scheme css file. + * Registers an admin colour scheme css file. * - * Allows a plugin to register a new admin colour scheme. - * For Example: + * Allows a plugin to register a new admin colour scheme. For example: * - * wp_admin_css_color('classic', __('Classic'), admin_url("css/colors-classic.css"), array('#07273E', '#14568A', '#D54E21', '#2683AE')); + * wp_admin_css_color('classic', __('Classic'), admin_url("css/colors-classic.css"), + * array('#07273E', '#14568A', '#D54E21', '#2683AE')); * * + * @since 2.5.0 + * * @param string $key The unique key for this theme. * @param string $name The name of the theme. * @param string $url The url of the css file containing the colour scheme. * @param array @colors An array of CSS color definitions which are used to give the user a feel for the theme. - * - * @since 2.5.0 */ function wp_admin_css_color($key, $name, $url, $colors = array()) { global $_wp_admin_css_colors; @@ -1523,7 +1556,7 @@ function wp_admin_css_color($key, $name, $url, $colors = array()) { } /** - * Outputs the URL of a WordPress admin CSS file + * Display the URL of a WordPress admin CSS file. * * @see WP_Styles::_css_href and its style_loader_src filter. * @@ -1545,18 +1578,19 @@ function wp_admin_css_uri( $file = 'wp-admin' ) { /** * Enqueues or directly prints a stylesheet link to the specified CSS file. * - * "Intelligently" decides to enqueue or to print the CSS file. - * If the wp_print_styles action has *not* yet been called, the CSS file will be enqueued. - * If the wp_print_styles action *has* been called, the CSS link will be printed. - * Printing may be forced by passing TRUE as the $force_echo (second) parameter. + * "Intelligently" decides to enqueue or to print the CSS file. If the + * 'wp_print_styles' action has *not* yet been called, the CSS file will be + * enqueued. If the wp_print_styles action *has* been called, the CSS link will + * be printed. Printing may be forced by passing TRUE as the $force_echo + * (second) parameter. * - * For backward compatibility with WordPress 2.3 calling method: - * If the $file (first) parameter does not correspond to a registered CSS file, we assume $file is a - * file relative to wp-admin/ without its ".css" extension. A stylesheet link to that generated URL is printed. + * For backward compatibility with WordPress 2.3 calling method: If the $file + * (first) parameter does not correspond to a registered CSS file, we assume + * $file is a file relative to wp-admin/ without its ".css" extension. A + * stylesheet link to that generated URL is printed. * * @package WordPress - * @since 2.3 - * + * @since 2.3.0 * @uses $wp_styles WordPress Styles Object * * @param string $file Style handle name or file name (without ".css" extension) relative to wp-admin/ @@ -1587,11 +1621,11 @@ function wp_admin_css( $file = 'wp-admin', $force_echo = false ) { /** * Enqueues the default ThickBox js and css. * - * If any of the settings need to be changed, this can be done with another js file - * similar to media-upload.js and theme-preview.js. That file should require array('thickbox') - * to ensure it is loaded after. - * - * @since 0.0 + * If any of the settings need to be changed, this can be done with another js + * file similar to media-upload.js and theme-preview.js. That file should + * require array('thickbox') to ensure it is loaded after. + * + * @since 2.5.0 */ function add_thickbox() { wp_enqueue_script( 'thickbox' ); @@ -1599,23 +1633,22 @@ function add_thickbox() { } /** - * Outputs the XHTML generator that is generated on the wp_head hook. - * - * @since 2.5 + * Display the XHTML generator that is generated on the wp_head hook. + * + * @since 2.5.0 */ function wp_generator() { the_generator( apply_filters( 'wp_generator_type', 'xhtml' ) ); } /** - * Outputs the generator XML or Comment for RSS, ATOM, etc. + * Display the generator XML or Comment for RSS, ATOM, etc. * - * Returns the correct generator type for the requested output format. - * - * Allows for a plugin to filter generators overall the the_generator filter. + * Returns the correct generator type for the requested output format. Allows + * for a plugin to filter generators overall the the_generator filter. * - * @since 2.5 - * @uses apply_filters() the_generator + * @since 2.5.0 + * @uses apply_filters() Calls 'the_generator' hook. * * @param string $type The type of generator to output - (html|xhtml|atom|rss2|rdf|comment|export). */ @@ -1626,14 +1659,15 @@ function the_generator( $type ) { /** * Creates the generator XML or Comment for RSS, ATOM, etc. * - * Returns the correct generator type for the requested output format. - * - * Allows for a plugin to filter generators on an individual basis using the get_the_generator_{$type} filter. + * Returns the correct generator type for the requested output format. Allows + * for a plugin to filter generators on an individual basis using the + * 'get_the_generator_{$type}' filter. * - * @since 2.5 - * @uses apply_filters() get_the_generator_{$type} + * @since 2.5.0 + * @uses apply_filters() Calls 'get_the_generator_$type' hook. * * @param string $type The type of generator to return - (html|xhtml|atom|rss2|rdf|comment|export). + * @return string The HTML content for the generator. */ function get_the_generator( $type ) { switch ($type) {