Changeset 8835

Show
Ignore:
Timestamp:
09/06/08 06:38:26 (3 months ago)
Author:
westi
Message:

General Template function phpdoc updates. See #5640 props jacobsantos.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/general-template.php

    r8823 r8835  
    1010 * Load header template. 
    1111 * 
    12  * Includes the header template for a theme or if a name is specified then a specialised header will be included. 
    13  * If the theme contains no header.php file then the header from the default theme will be included. 
     12 * Includes the header template for a theme or if a name is specified then a 
     13 * specialised header will be included. If the theme contains no header.php file 
     14 * then the header from the default theme will be included. 
     15 * 
     16 * For the parameter, if the file is called "header-special.php" then specify 
     17 * "special". 
    1418 * 
    1519 * @uses locate_template() 
    1620 * @since 1.5.0 
    1721 * @uses do_action() Calls 'get_header' action. 
    18  * @param $name String The name of the specialised header. If the file is called "header-special.php" then specify "special". 
     22 * 
     23 * @param string $name The name of the specialised header. 
    1924 */ 
    2025function get_header( $name = null ) { 
    …… 
    3439 * Load footer template. 
    3540 * 
    36  * Includes the footer template for a theme or if a name is specified then a specialised footer will be included. 
    37  * If the theme contains no footer.php file then the footer from the default theme will be included. 
     41 * Includes the footer template for a theme or if a name is specified then a 
     42 * specialised footer will be included. If the theme contains no footer.php file 
     43 * then the footer from the default theme will be included. 
     44 * 
     45 * For the parameter, if the file is called "footer-special.php" then specify 
     46 * "special". 
    3847 * 
    3948 * @uses locate_template() 
    4049 * @since 1.5.0 
    4150 * @uses do_action() Calls 'get_footer' action. 
    42  * @param $name String The name of the specialised footer. If the file is called "footer-special.php" then specify "special". 
     51 * 
     52 * @param string $name The name of the specialised footer. 
    4353 */ 
    4454function get_footer( $name = null ) { 
    …… 
    5868 * Load sidebar template. 
    5969 * 
    60  * Includes the sidebar template for a theme or if a name is specified then a specialised sidebar will be included. 
    61  * If the theme contains no sidebar.php file then the sidebar from the default theme will be included. 
     70 * Includes the sidebar template for a theme or if a name is specified then a 
     71 * specialised sidebar will be included. If the theme contains no sidebar.php 
     72 * file then the sidebar from the default theme will be included. 
     73 * 
     74 * For the parameter, if the file is called "sidebar-special.php" then specify 
     75 * "special". 
    6276 * 
    6377 * @uses locate_template() 
    6478 * @since 1.5.0 
    6579 * @uses do_action() Calls 'get_sidebar' action. 
    66  * @param $name String The name of the specialised sidebar. If the file is called "sidebar-special.php" then specify "special". 
     80 * 
     81 * @param string $name The name of the specialised sidebar. 
    6782 */ 
    6883function get_sidebar( $name = null ) { 
    …… 
    8095 
    8196/** 
    82  * Echo the Log In/Out link 
    83  * 
    84  * 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. 
     97 * Display the Log In/Out link. 
     98 * 
     99 * Displays a link, which allows the user to navigate to the Login page to login 
     100 * or logout depending on whether or not they are currently logged in. 
    85101 * 
    86102 * @since 1.5.0 
    87  * @uses apply_filters()  
     103 * @uses apply_filters() Calls 'loginout' hook on HTML link content. 
    88104 */ 
    89105function wp_loginout() { 
    …… 
    97113 
    98114/** 
    99 * Echo the Registration or Admin link 
    100  * 
    101  * 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. 
     115 * Display the Registration or Admin link. 
     116 * 
     117 * Display a link which allows the user to navigate to the registration page if 
     118 * not logged in and registration is enabled or to the dashboard if logged in. 
    102119 *  
    103120 * @since 1.5.0 
    104  * @uses apply_filters()  
    105  * 
    106  * @param String $before Text to output before the link (defaults to <li>). 
    107  * @param String $after Text to output after the link (defaults to </li>). 
     121 * @uses apply_filters() Calls 'register' hook on register / admin link content. 
     122 * 
     123 * @param string $before Text to output before the link (defaults to <li>). 
     124 * @param string $after Text to output after the link (defaults to </li>). 
    108125 */ 
    109126function wp_register( $before = '<li>', $after = '</li>' ) { 
    …… 
    128145 * 
    129146 * @since 1.5.0 
    130  * @link http://trac.wordpress.org/ticket/1458 Explaination of 'wp_meta' action. 
     147 * @link http://trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action. 
    131148 * @uses do_action() Calls 'wp_meta' hook. 
    132149 */ 
    …… 
    136153 
    137154/** 
    138  * bloginfo() - {@internal Missing Short Description}} 
    139  * 
    140  * {@internal Missing Long Description}} 
    141  * 
     155 * Display information about the blog. 
     156 * 
     157 * @see get_bloginfo() For possible values for the parameter. 
    142158 * @since 0.71 
    143159 * 
    144  * @param unknown_type $show 
     160 * @param string $show What to display. 
    145161 */ 
    146162function bloginfo($show='') { 
    …… 
    149165 
    150166/** 
    151  * get_bloginfo() - {@internal Missing Short Description}} 
    152  * 
    153  * {@internal Missing Long Description}} 
    154  * 
    155  * Note: some of these values are DEPRECATED. Meaning they could be 
    156  * taken out at any time and shouldn't be relied upon. Options 
    157  * without "// DEPRECATED" are the preferred and recommended ways 
    158  * to get the information. 
     167 * Retrieve information about the blog. 
     168 * 
     169 * Some show parameter values are deprecated and will be removed in future 
     170 * versions. Care should be taken to check the function contents and know what 
     171 * the deprecated blog info options are. Options without "// DEPRECATED" are 
     172 * the preferred and recommended ways to get the information. 
     173 * 
     174 * The possible values for the 'show' parameter are listed below. 
     175 * <ol> 
     176 * <li><strong>url<strong> - Blog URI to homepage.</li> 
     177 * <li><strong>wpurl</strong> - Blog URI path to WordPress.</li> 
     178 * <li><strong>description</strong> - Secondary title</li> 
     179 * </ol> 
     180 * 
     181 * The feed URL options can be retrieved from 'rdf_url' (RSS 0.91), 
     182 * 'rss_url' (RSS 1.0), 'rss2_url' (RSS 2.0), or 'atom_url' (Atom feed). The 
     183 * comment feeds can be retrieved from the 'comments_atom_url' (Atom comment 
     184 * feed) or 'comments_rss2_url' (RSS 2.0 comment feed). 
     185 * 
     186 * There are many other options and you should check the function contents: 
     187 * {@source 32 37} 
    159188 * 
    160189 * @since 0.71 
    161190 * 
    162  * @param unknown_type $show 
    163  * @param unknown_type $filter 
    164  * @return unknown 
     191 * @param string $show Blog info to retrieve. 
     192 * @param string $filter How to filter what is retrieved. 
     193 * @return string Mostly string values, might be empty. 
    165194 */ 
    166195function get_bloginfo($show = '', $filter = 'raw') { 
    …… 
    254283 
    255284/** 
    256  * wp_title() - {@internal Missing Short Description}} 
     285 * {@internal Missing Short Description}} 
    257286 * 
    258287 * {@internal Missing Long Description}} 
    …… 
    370399 
    371400/** 
    372  * single_post_title() - {@internal Missing Short Description}} 
     401 * {@internal Missing Short Description}} 
    373402 * 
    374403 * {@internal Missing Long Description}} 
    …… 
    400429 
    401430/** 
    402  * single_cat_title() - {@internal Missing Short Description}} 
     431 * {@internal Missing Short Description}} 
    403432 * 
    404433 * {@internal Missing Long Description}} 
    …… 
    426455 
    427456/** 
    428  * single_tag_title() - {@internal Missing Short Description}} 
     457 * {@internal Missing Short Description}} 
    429458 * 
    430459 * {@internal Missing Long Description}} 
    …… 
    457486 
    458487/** 
    459  * single_month_title() - {@internal Missing Short Description}} 
     488 * {@internal Missing Short Description}} 
    460489 * 
    461490 * {@internal Missing Long Description}} 
    …… 
    493522 
    494523/** 
    495  * get_archives_link() - {@internal Missing Short Description}} 
     524 * {@internal Missing Short Description}} 
    496525 * 
    497526 * {@internal Missing Long Description}} 
    …… 
    528557 
    529558/** 
    530  * wp_get_archives() - {@internal Missing Short Description}} 
     559 * {@internal Missing Short Description}} 
    531560 * 
    532561 * {@internal Missing Long Description}} 
    …… 
    702731 
    703732/** 
    704  * calendar_week_mod() - {@internal Missing Short Description}} 
     733 * {@internal Missing Short Description}} 
    705734 * 
    706735 * {@internal Missing Long Description}} 
    …… 
    709738 * @usedby get_calendar() 
    710739 * 
    711  * @param unknown_type $num 
    712  * @return unknown 
     740 * @param int $num Number of day. 
     741 * @return int 
    713742 */ 
    714743function calendar_week_mod($num) { 
    …… 
    718747 
    719748/** 
    720  * get_calendar() - {@internal Missing Short Description}} 
     749 * {@internal Missing Short Description}} 
    721750 * 
    722751 * {@internal Missing Long Description}} 
    …… 
    934963 
    935964/** 
    936  * allowed_tags() - {@internal Missing Short Description}} 
     965 * {@internal Missing Short Description}} 
    937966 * 
    938967 * {@internal Missing Long Description}} 
    …… 
    961990 
    962991/** 
    963  * Outputs the date in iso8601 format for xml files, 
     992 * Outputs the date in iso8601 format for xml files. 
    964993 * 
    965994 * @since 1.0.0 
    …… 
    9711000 
    9721001/** 
    973  * Echos or Returns the date the post was written. 
    974  * 
    975  * Will only output the date if the current post's date is different from the previous one output. 
     1002 * Display or Retrieve the date the post was written. 
     1003 * 
     1004 * Will only output the date if the current post's date is different from the 
     1005 * previous one output. 
    9761006 * 
    9771007 * @since 0.71 
    9781008 * 
    979  * @param string $d php date format defaults to the date_format option if not specified. 
    980  * @param string $before output before the date. 
    981  * @param string $after output after the date. 
    982  * @param bool $echo Whether to echo the date or return it. 
    983  * @return unknown 
     1009 * @param string $d Optional. PHP date format defaults to the date_format option if not specified. 
     1010 * @param string $before Optional. Output before the date. 
     1011 * @param string $after Optional. Output after the date. 
     1012 * @param bool $echo Optional, default is display. Whether to echo the date or return it. 
     1013 * @return string|null Null if displaying, string if retrieving. 
    9841014 */ 
    9851015function the_date($d='', $before='', $after='', $echo = true) { 
    …… 
    10031033 
    10041034/** 
    1005  * Outputs the date on which the post was last modified. 
     1035 * Display the date on which the post was last modified. 
    10061036 * 
    10071037 * @since 2.1.0 
    10081038 * 
    1009  * @param string $d php date format. 
     1039 * @param string $d Optional. PHP date format. 
    10101040 * @return string 
    10111041 */ 
    …… 
    10151045 
    10161046/** 
    1017  * Returns the date on which the post was last modified. 
     1047 * Retrieve the date on which the post was last modified. 
    10181048 * 
    10191049 * @since 2.1.0 
    10201050 * 
    1021  * @param string $d php date format. Defaults to the "date_format" option 
     1051 * @param string $d Optional. PHP date format. Defaults to the "date_format" option 
    10221052 * @return string 
    10231053 */ 
    …… 
    10311061 
    10321062/** 
    1033  * Output the time at which the post was written. 
     1063 * Display the time at which the post was written. 
    10341064 * 
    10351065 * @since 0.71 
    …… 
    10421072 
    10431073/** 
    1044  * Returns the time at which the post was written. 
     1074 * Retrieve the time at which the post was written. 
    10451075 * 
    10461076 * @since 1.5.0 
    …… 
    10581088 
    10591089/** 
    1060  * Returns the time at which the post was written 
     1090 * Retrieve the time at which the post was written. 
    10611091 * 
    10621092 * @since 2.0.0 
    …… 
    10781108 
    10791109/** 
    1080  * the_modified_time() - {@internal Missing Short Description}} 
    1081  * 
    1082  * {@internal Missing Long Description}} 
     1110 * Display the time at which the post was last modified. 
    10831111 * 
    10841112 * @since 2.0.0 
    10851113 * 
    1086  * @param unknown_type $d 
     1114 * @param string $d Either 'G', 'U', or php date format defaults to the value specified in the time_format option. 
    10871115 */ 
    10881116function the_modified_time($d = '') { 
    …… 
    10911119 
    10921120/** 
    1093  * Returns the time at which the post was last modified. 
     1121 * Retrieve the time at which the post was last modified. 
    10941122 * 
    10951123 * @since 2.0.0 
    …… 
    11071135 
    11081136/** 
    1109  * Returns the time at which the post was last modified. 
     1137 * Retrieve the time at which the post was last modified. 
    11101138 * 
    11111139 * @since 2.0.0 
    …… 
    11131141 * @param string $d Either 'G', 'U', or php date format. 
    11141142 * @param bool $gmt Whether of not to return the gmt time. 
    1115  * @return string 
    1116  */ 
    1117 function get_post_modified_time( $d = 'U', $gmt = false ) { // returns timestamp 
     1143 * @return string Returns timestamp 
     1144 */ 
     1145function get_post_modified_time( $d = 'U', $gmt = false ) { 
    11181146    global $post; 
    11191147 
    …… 
    11281156 
    11291157/** 
    1130  * Outputs the weekday on which the post was written. 
     1158 * Display the weekday on which the post was written. 
    11311159 * 
    11321160 * @since 0.71 
    …… 
    11421170 
    11431171/** 
    1144  * Outputs the weekday on which the post was written. 
    1145  * 
    1146  * Will only output the weekday if the current post's weekday is different from the previous one output. 
     1172 * Display the weekday on which the post was written. 
     1173 * 
     1174 * Will only output the weekday if the current post's weekday is different from 
     1175 * the previous one output. 
    11471176 * 
    11481177 * @since 0.71 
    …… 
    11681197 * 
    11691198 * @since 1.2.0 
    1170  * @uses do_action()  
     1199 * @uses do_action() Calls 'wp_head' hook. 
    11711200 */ 
    11721201function wp_head() { 
    …… 
    11781207 * 
    11791208 * @since 1.5.1 
    1180  * @uses do_action()  
     1209 * @uses do_action() Calls 'wp_footer' hook. 
    11811210 */ 
    11821211function wp_footer() { 
    …… 
    11851214 
    11861215/** 
    1187  * Outputs the link to the Really Simple Discovery service endpoint. 
     1216 * Display the link to the Really Simple Discovery service endpoint. 
    11881217 * 
    11891218 * @link http://archipelago.phrasewise.com/rsd 
    …… 
    11951224 
    11961225/** 
    1197  * Outputs the link to the Windows Live Writer manifest file. 
     1226 * Display the link to the Windows Live Writer manifest file. 
    11981227 * 
    11991228 * @link http://msdn.microsoft.com/en-us/library/bb463265.aspx 
    …… 
    12061235 
    12071236/** 
    1208  * Outputs a noindex meta tag if required by the blog configuration. 
    1209  * 
    1210  * 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. 
     1237 * Display a noindex meta tag if required by the blog configuration. 
     1238 * 
     1239 * If a blog is marked as not being public then the noindex meta tag will be 
     1240 * output to tell web robots not to index the page content. 
    12111241 * 
    12121242 * @since 2.1.0 
    …… 
    12371267 * Whether or not the user should have a WYSIWIG editor. 
    12381268 * 
    1239  * Checks that the user requires a WYSIWIG editor and that the editor is supported in the users browser. 
     1269 * Checks that the user requires a WYSIWIG editor and that the editor is 
     1270 * supported in the users browser. 
    12401271 * 
    12411272 * @since 2.0.0 
    …… 
    12611292 
    12621293/** 
    1263  * Find out which editor should be displayed by default 
    1264  * 
    1265  * Works out which of the two editors to display as the current editor for a user. 
     1294 * Find out which editor should be displayed by default. 
     1295 * 
     1296 * Works out which of the two editors to display as the current editor for a 
     1297 * user. 
    12661298 * 
    12671299 * @since 2.5.0 
    …… 
    12791311 
    12801312/** 
    1281  * the_editor() - {@internal Missing Short Description}} 
     1313 * {@internal Missing Short Description}} 
    12821314 * 
    12831315 * {@internal Missing Long Description}} 
    …… 
    13561388 
    13571389/** 
    1358  * Returns the contents of the search query variable 's' 
     1390 * Retrieve the contents of the search WordPress query variable. 
    13591391 * 
    13601392 * @since 2.3.0 
    …… 
    13671399 
    13681400/** 
    1369  * Outputs the contents of the search query variable 's' 
     1401 * Display the contents of the search query variable. 
    13701402 *  
    1371  * The search query string is paseed through attribute_escape to ensure that it is safe for placing in an html attribute 
     1403 * The search query string is passed through {@link attribute_escape()} 
     1404 * to ensure that it is safe for placing in an html attribute. 
    13721405 * 
    13731406 * @uses attribute_escape 
    13741407 * @since 2.1.0 
    1375  * 
    13761408 */ 
    13771409function the_search_query() { 
    …… 
    13801412 
    13811413/** 
    1382  * Outputs the language attributes for the html tag. 
    1383  * 
    1384  * Builds up a set of html attributes containing the text direction and language information for the page. 
     1414 * Display the language attributes for the html tag. 
     1415 * 
     1416 * Builds up a set of html attributes containing the text direction and language 
     1417 * information for the page. 
    13851418 * 
    13861419 * @since 2.1.0 
    …… 
    14091442 
    14101443/** 
    1411  * paginate_links() - {@internal Missing Short Description}} 
     1444 * {@internal Missing Short Description}} 
    14121445 * 
    14131446 * {@internal Missing Long Description}} 
    …… 
    14991532 
    15001533/** 
    1501  * Registers a admin colour scheme css file. 
    1502  * 
    1503  * Allows a plugin to register a new admin colour scheme. 
    1504  * For Example: 
     1534 * Registers an admin colour scheme css file. 
     1535 * 
     1536 * Allows a plugin to register a new admin colour scheme. For example: 
    15051537 * <code> 
    1506  * wp_admin_css_color('classic', __('Classic'), admin_url("css/colors-classic.css"), array('#07273E', '#14568A', '#D54E21', '#2683AE')); 
     1538 * wp_admin_css_color('classic', __('Classic'), admin_url("css/colors-classic.css"), 
     1539 * array('#07273E', '#14568A', '#D54E21', '#2683AE')); 
    15071540 * </code> 
     1541 * 
     1542 * @since 2.5.0 
    15081543 * 
    15091544 * @param string $key The unique key for this theme. 
    …… 
    15111546 * @param string $url The url of the css file containing the colour scheme. 
    15121547 * @param array @colors An array of CSS color definitions which are used to give the user a feel for the theme. 
    1513  *  
    1514  * @since 2.5.0 
    15151548 */ 
    15161549function wp_admin_css_color($key, $name, $url, $colors = array()) { 
    …… 
    15241557 
    15251558/** 
    1526  * Outputs the URL of a WordPress admin CSS file 
     1559 * Display the URL of a WordPress admin CSS file. 
    15271560 * 
    15281561 * @see WP_Styles::_css_href and its style_loader_src filter. 
    …… 
    15461579 * Enqueues or directly prints a stylesheet link to the specified CSS file. 
    15471580 * 
    1548  * "Intelligently" decides to enqueue or to print the CSS file. 
    1549  * If the wp_print_styles action has *not* yet been called, the CSS file will be enqueued. 
    1550  * If the wp_print_styles action *has* been called, the CSS link will be printed. 
    1551  * Printing may be forced by passing TRUE as the $force_echo (second) parameter. 
    1552  * 
    1553  * For backward compatibility with WordPress 2.3 calling method: 
    1554  * If the $file (first) parameter does not correspond to a registered CSS file, we assume $file is a 
    1555  * file relative to wp-admin/ without its ".css" extension.  A stylesheet link to that generated URL is printed. 
     1581 * "Intelligently" decides to enqueue or to print the CSS file. If the 
     1582 * 'wp_print_styles' action has *not* yet been called, the CSS file will be 
     1583 * enqueued. If the wp_print_styles action *has* been called, the CSS link will 
     1584 * be printed. Printing may be forced by passing TRUE as the $force_echo 
     1585 * (second) parameter. 
     1586 * 
     1587 * For backward compatibility with WordPress 2.3 calling method: If the $file 
     1588 * (first) parameter does not correspond to a registered CSS file, we assume 
     1589 * $file is a file relative to wp-admin/ without its ".css" extension. A 
     1590 * stylesheet link to that generated URL is printed. 
    15561591 * 
    15571592 * @package WordPress 
    1558  * @since 2.3 
    1559  * 
     1593 * @since 2.3.0 
    15601594 * @uses $wp_styles WordPress Styles Object 
    15611595 * 
    …… 
    15881622 * Enqueues the default ThickBox js and css.  
    15891623 *  
    1590  * If any of the settings need to be changed, this can be done with another js file 
    1591  * similar to media-upload.js and theme-preview.js. That file should require array('thickbox') 
    1592  * to ensure it is loaded after. 
    1593  *   
    1594  * @since 0.0 
     1624 * If any of the settings need to be changed, this can be done with another js 
     1625 * file similar to media-upload.js and theme-preview.js. That file should 
     1626 * require array('thickbox') to ensure it is loaded after. 
     1627 * 
     1628 * @since 2.5.0 
    15951629 */ 
    15961630function add_thickbox() { 
    …… 
    16001634 
    16011635/** 
    1602  * Outputs the XHTML generator that is generated on the wp_head hook. 
    1603  *  
    1604  * @since 2.5 
     1636 * Display the XHTML generator that is generated on the wp_head hook. 
     1637 * 
     1638 * @since 2.5.0 
    16051639 */ 
    16061640function wp_generator() { 
    …… 
    16091643 
    16101644/** 
    1611  * Outputs the generator XML or Comment for RSS, ATOM, etc. 
    1612  * 
    1613  * Returns the correct generator type for the requested output format. 
    1614  *  
    1615  * Allows for a plugin to filter generators overall the the_generator filter. 
    1616  * 
    1617  * @since 2.5 
    1618  * @uses apply_filters() the_generator 
     1645 * Display the generator XML or Comment for RSS, ATOM, etc. 
     1646 * 
     1647 * Returns the correct generator type for the requested output format. Allows 
     1648 * for a plugin to filter generators overall the the_generator filter. 
     1649 * 
     1650 * @since 2.5.0 
     1651 * @uses apply_filters() Calls 'the_generator' hook. 
    16191652 * 
    16201653 * @param string $type The type of generator to output - (html|xhtml|atom|rss2|rdf|comment|export). 
    …… 
    16271660 * Creates the generator XML or Comment for RSS, ATOM, etc. 
    16281661 * 
    1629  * Returns the correct generator type for the requested output format. 
    1630  *  
    1631  * Allows for a plugin to filter generators on an individual basis using the get_the_generator_{$type} filter. 
    1632  * 
    1633  * @since 2.5 
    1634  * @uses apply_filters() get_the_generator_{$type} 
     1662 * Returns the correct generator type for the requested output format. Allows 
     1663 * for a plugin to filter generators on an individual basis using the 
     1664 * 'get_the_generator_{$type}' filter. 
     1665 * 
     1666 * @since 2.5.0 
     1667 * @uses apply_filters() Calls 'get_the_generator_$type' hook. 
    16351668 * 
    16361669 * @param string $type The type of generator to return - (html|xhtml|atom|rss2|rdf|comment|export). 
     1670 * @return string The HTML content for the generator. 
    16371671 */ 
    16381672function get_the_generator( $type ) {