Ticket #5640: 5640.r8831.diff

general-template.php

@@ -9 +9 @@
 /**
  * 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 +38 @@
 /**
  * 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 +67 @@
 /**
  * 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 +94 @@
 }
 
 /**
- * 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 +112 @@
 }
 
 /**
-* 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 <li>).
- * @param String $after Text to output after the link (defaults to </li>).
+ * @param string $before Text to output before the link (defaults to <li>).
+ * @param string $after Text to output after the link (defaults to </li>).
  */
 function wp_register( $before = '<li>', $after = '</li>' ) {
 
@@ -127 +144 @@
  * 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 +152 @@
 }
 
 /**
- * bloginfo() - {@internal Missing Short Description}}
+ * Display information about the blog.
  *
- * {@internal Missing Long Description}}
- *
+ * @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.
+ * <ol>
+ * <li><strong>url<strong> - Blog URI to homepage.</li>
+ * <li><strong>wpurl</strong> - Blog URI path to WordPress.</li>
+ * <li><strong>description</strong> - Secondary title</li>
+ * </ol>
  *
+ * 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 +282 @@
 }
 
 /**
- * wp_title() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -369 +398 @@
 }
 
 /**
- * single_post_title() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -399 +428 @@
 }
 
 /**
- * single_cat_title() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -425 +454 @@
 }
 
 /**
- * single_tag_title() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -456 +485 @@
 }
 
 /**
- * single_month_title() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -492 +521 @@
 }
 
 /**
- * get_archives_link() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -527 +556 @@
 }
 
 /**
- * wp_get_archives() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -701 +730 @@
 }
 
 /**
- * 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 +746 @@
 }
 
 /**
- * get_calendar() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -933 +962 @@
 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 +989 @@
 /***** 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 +999 @@
 }
 
 /**
- * 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 +1032 @@
 }
 
 /**
- * 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 +1044 @@
 }
 
 /**
- * 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 +1060 @@
 }
 
 /**
- * Output the time at which the post was written.
+ * Display the time at which the post was written.
  *
  * @since 0.71
  *
@@ -1041 +1071 @@
 }
 
 /**
- * Returns the time at which the post was written.
+ * Retrieve the time at which the post was written.
  *
  * @since 1.5.0
  *
@@ -1057 +1087 @@
 }
 
 /**
- * Returns the time at which the post was written
+ * Retrieve the time at which the post was written.
  *
  * @since 2.0.0
  *
@@ -1077 +1107 @@
 }
 
 /**
- * the_modified_time() - {@internal Missing Short Description}}
+ * Display the time at which the post was last modified.
  *
- * {@internal Missing Long Description}}
- *
  * @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 +1134 @@
 }
 
 /**
- * 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 +1155 @@
 }
 
 /**
- * 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 +1169 @@
 }
 
 /**
- * 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 +1196 @@
  * 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 +1206 @@
  * 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 +1223 @@
 }
 
 /**
- * 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 +1234 @@
 }
 
 /**
- * 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 +1266 @@
 /**
  * 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 +1291 @@
 }
 
 /**
- * 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 +1310 @@
 }
 
 /**
- * the_editor() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -1355 +1387 @@
 }
 
 /**
- * Returns the contents of the search query variable 's'
+ * Retrieve the contents of the search WordPress query variable.
  *
  * @since 2.3.0
  *
@@ -1366 +1398 @@
 }
 
 /**
- * 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 +1441 @@
 }
 
 /**
- * paginate_links() - {@internal Missing Short Description}}
+ * {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -1498 +1531 @@
 }
 
 /**
- * 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:
  * <code>
- * 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'));
  * </code>
  *
+ * @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 +1556 @@
 }
 
 /**
- * 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 +1578 @@
 /**
  * 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 +1621 @@
 /**
  * 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 +1633 @@
 }
 
 /**
- * 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 +1659 @@
 /**
  * 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) {