WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
09/06/2008 06:38:26 AM (17 years ago)
Author:
westi
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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 ) {
Note: See TracChangeset for help on using the changeset viewer.