Ticket #5640: 5640.r8857.diff

general-template.php

@@ -282 +282 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display or retrieve page title for all areas of blog.
  *
- * {@internal Missing Long Description}}
+ * By default, the page title will display the separator before the page title,
+ * so that the blog title will be before the page title. This is not good for
+ * title display, since the blog title shows up on most tabs and not what is
+ * important, which is the page that the user is looking at.
  *
+ * There are also SEO benefits to having the blog title after or to the 'right'
+ * or the page title. However, it is mostly common sense to have the blog title
+ * to the right with most browsers supporting tabs. You can achieve this by
+ * using the seplocation parameter and setting the value to 'right'. This change
+ * was introduced around 2.5.0, in case backwards compatibility of themes is
+ * important.
+ *
  * @since 1.0.0
  *
- * @param unknown_type $sep
- * @param unknown_type $display
- * @return unknown
+ * @param string $sep Optional, default is '»'. How to separate the various items within the page title.
+ * @param bool $display Optional, default is true. Whether to display or retrieve title.
+ * @param string $seplocation Optional. Direction to display title, 'right'.
+ * @return string|null String on retrieve, null when displaying.
  */
 function wp_title($sep = '»', $display = true, $seplocation = '') {
         global $wpdb, $wp_locale, $wp_query;
@@ -398 +409 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display or retrieve page title for post.
  *
- * {@internal Missing Long Description}}
+ * This is optimized for single.php template file for displaying the post title.
+ * Only useful for posts, does not support pages for example.
  *
+ * It does not support placing the separator after the title, but by leaving the
+ * prefix parameter empty, you can set the title separator manually. The prefix
+ * does not automatically place a space between the prefix, so if there should
+ * be a space, the parameter value will need to have it at the end.
+ *
  * @since 0.71
  * @uses $wpdb
  *
- * @param unknown_type $prefix
- * @param unknown_type $display
- * @return unknown
+ * @param string $prefix Optional. What to display before the title.
+ * @param bool $display Optional, default is true. Whether to display or retrieve title.
+ * @return string|null Title when retrieving, null when displaying or failure.
  */
 function single_post_title($prefix = '', $display = true) {
         global $wpdb;
@@ -428 +445 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display or retrieve page title for category archive.
  *
- * {@internal Missing Long Description}}
+ * This is useful for category template file or files, because it is optimized
+ * for category page title and with less overhead than {@link wp_title()}.
  *
+ * It does not support placing the separator after the title, but by leaving the
+ * prefix parameter empty, you can set the title separator manually. The prefix
+ * does not automatically place a space between the prefix, so if there should
+ * be a space, the parameter value will need to have it at the end.
+ *
  * @since 0.71
  *
- * @param unknown_type $prefix
- * @param unknown_type $display
- * @return unknown
+ * @param string $prefix Optional. What to display before the title.
+ * @param bool $display Optional, default is true. Whether to display or retrieve title.
+ * @return string|null Title when retrieving, null when displaying or failure.
  */
 function single_cat_title($prefix = '', $display = true ) {
         $cat = intval( get_query_var('cat') );
@@ -454 +477 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display or retrieve page title for tag post archive.
  *
- * {@internal Missing Long Description}}
+ * Useful for tag template files for displaying the tag page title. It has less
+ * overhead than {@link wp_title()}, because of its limited implementation.
  *
+ * It does not support placing the separator after the title, but by leaving the
+ * prefix parameter empty, you can set the title separator manually. The prefix
+ * does not automatically place a space between the prefix, so if there should
+ * be a space, the parameter value will need to have it at the end.
+ *
  * @since 2.3.0
  *
- * @param unknown_type $prefix
- * @param unknown_type $display
- * @return unknown
+ * @param string $prefix Optional. What to display before the title.
+ * @param bool $display Optional, default is true. Whether to display or retrieve title.
+ * @return string|null Title when retrieving, null when displaying or failure.
  */
 function single_tag_title($prefix = '', $display = true ) {
         if ( !is_tag() )
@@ -485 +514 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display or retrieve page title for post archive based on date.
  *
- * {@internal Missing Long Description}}
+ * Useful for when the template only needs to display the month and year, if
+ * either are available. Optimized for just this purpose, so if it is all that
+ * is needed, should be better than {@link wp_title()}.
  *
+ * It does not support placing the separator after the title, but by leaving the
+ * prefix parameter empty, you can set the title separator manually. The prefix
+ * does not automatically place a space between the prefix, so if there should
+ * be a space, the parameter value will need to have it at the end.
+ *
  * @since 0.71
  *
- * @param unknown_type $prefix
- * @param unknown_type $display
- * @return unknown
+ * @param string $prefix Optional. What to display before the title.
+ * @param bool $display Optional, default is true. Whether to display or retrieve title.
+ * @return string|null Title when retrieving, null when displaying or failure.
  */
 function single_month_title($prefix = '', $display = true ) {
         global $wp_locale;
@@ -521 +557 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Retrieve archive link content based on predefined or custom code.
  *
- * {@internal Missing Long Description}}
+ * The format can be one of four styles. The 'link' for head element, 'option'
+ * for use in the select element, 'html' for use in list (either ol or ul HTML
+ * elements). Custom content is also supported using the before and after
+ * parameters.
  *
+ * The 'link' format uses the link HTML element with the <em>archives</em>
+ * relationship. The before and after parameters are not used. The text
+ * parameter is used to describe the link.
+ *
+ * The 'option' format uses the option HTML element for use in select element.
+ * The value is the url parameter and the before and after parameters are used
+ * between the text description.
+ *
+ * The 'html' format, which is the default, uses the li HTML element for use in
+ * the list HTML elements. The before parameter is before the link and the after
+ * parameter is after the closing link.
+ *
+ * The custom format uses the before parameter before the link ('a' HTML
+ * element) and the after parameter after the closing link tag. If the above
+ * three values for the format are not used, then custom format is assumed.
+ *
  * @since 1.0.0
  * @author Orien
  * @link http://icecode.com/ link navigation hack by Orien
  *
- * @param unknown_type $url
- * @param unknown_type $text
- * @param unknown_type $format
- * @param unknown_type $before
- * @param unknown_type $after
- * @return unknown
+ * @param string $url URL to archive.
+ * @param string $text Archive text description.
+ * @param string $format Optional, default is 'html'. Can be 'link', 'option', 'html', or custom.
+ * @param string $before Optional.
+ * @param string $after Optional.
+ * @return string HTML link content for archive.
  */
 function get_archives_link($url, $text, $format = 'html', $before = '', $after = '') {
         $text = wptexturize($text);
@@ -556 +611 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display archive links based on type and format.
  *
- * {@internal Missing Long Description}}
+ * The 'type' argument offers a few choices and by default will display monthly
+ * archive links. The other options for values are 'daily', 'weekly', 'monthly',
+ * 'yearly', 'postbypost' or 'alpha'. Both 'postbypost' and 'alpha' display the
+ * same archive link list, the difference between the two is that 'alpha'
+ * will order by post title and 'postbypost' will order by post date.
  *
+ * The date archives will logically display dates with links to the archive post
+ * page. The 'postbypost' and 'alpha' values for 'type' argument will display
+ * the post titles.
+ *
+ * The 'limit' argument will only display a limited amount of links, specified
+ * by the 'limit' integer value. By default, there is no limit. The
+ * 'show_post_count' argument will show how many posts are within the archive.
+ * By default, the 'show_post_count' argument is set to false.
+ *
+ * For the 'format', 'before', and 'after' arguments, see {@link
+ * get_archives_link()}. The values of these arguments have to do with that
+ * function.
+ *
  * @since 1.2.0
  *
- * @param unknown_type $args
+ * @param string|array $args Optional. Override defaults.
  */
 function wp_get_archives($args = '') {
         global $wpdb, $wp_locale;
@@ -621 +693 @@
                 if ( $arcresults ) {
                         $afterafter = $after;
                         foreach ( (array) $arcresults as $arcresult ) {
-                                $url    = get_month_link($arcresult->year,      $arcresult->month);
+                                $url = get_month_link( $arcresult->year, $arcresult->month );
                                 $text = sprintf(__('%1$s %2$d'), $wp_locale->get_month($arcresult->month), $arcresult->year);
                                 if ( $show_post_count )
                                         $after = '&nbsp;('.$arcresult->posts.')' . $afterafter;
@@ -730 +802 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Get number of days since the start of the week.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.5.0
  * @usedby get_calendar()
  *
  * @param int $num Number of day.
- * @return int
+ * @return int Days since the start of the week.
  */
 function calendar_week_mod($num) {
         $base = 7;
@@ -746 +816 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display calendar with days that have posts as links.
  *
- * {@internal Missing Long Description}}
+ * The calendar is cached, which will be retrieved, if it exists. If there are
+ * no posts for the month, then it will not be displayed.
  *
  * @since 1.0.0
  *
- * @param unknown_type $initial
+ * @param bool $initial Optional, default is true. Use initial calendar names.
  */
 function get_calendar($initial = true) {
         global $wpdb, $m, $monthnum, $year, $wp_locale, $posts;
@@ -962 +1033 @@
 add_action( 'update_option_start_of_week', 'delete_get_calendar_cache' );
 
 /**
- * {@internal Missing Short Description}}
+ * Display all of the allowed tags in HTML format with attributes.
  *
- * {@internal Missing Long Description}}
+ * This is useful for displaying in the comment area, which elements and
+ * attributes are supported. As well as any plugins which want to display it.
  *
  * @since 1.0.1
  * @uses $allowedtags
  *
- * @return unknown
+ * @return string HTML allowed tags entity encoded.
  */
 function allowed_tags() {
         global $allowedtags;
@@ -1310 +1382 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display visual editor forms: TinyMCE, or HTML, or both.
  *
- * {@internal Missing Long Description}}
+ * The amount of rows the text area will have for the content has to be between
+ * 3 and 100 or will default at 12. There is only one option used for all users,
+ * named 'default_post_edit_rows'.
  *
+ * If the user can not use the rich editor (TinyMCE), then the switch button
+ * will not be displayed.
+ *
  * @since 2.1.0
  *
- * @param unknown_type $content
- * @param unknown_type $id
- * @param unknown_type $prev_id
+ * @param string $content Textarea content.
+ * @param string $id HTML ID attribute value.
+ * @param string $prev_id HTML ID name for switching back and forth between visual editors.
+ * @param bool $media_buttons Optional, default is true. Whether to display media buttons.
+ * @param int $tab_index Optional, default is 2. Tabindex for textarea element.
  */
 function the_editor($content, $id = 'content', $prev_id = 'title', $media_buttons = true, $tab_index = 2) {
         $rows = get_option('default_post_edit_rows');
@@ -1441 +1520 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Retrieve paginated link for archive post pages.
  *
- * {@internal Missing Long Description}}
+ * Technically, the function can be used to create paginated link list for any
+ * area. The 'base' argument is used to reference the url, which will be used to
+ * create the paginated links. The 'format' argument is then used for replacing
+ * the page number. It is however, most likely and by default, to be used on the
+ * archive post pages.
  *
+ * The 'type' argument controls format of the returned value. The default is
+ * 'plain', which is just a string with the links separated by a newline
+ * character. The other possible values are either 'array' or 'list'. The
+ * 'array' value will return an array of the paginated link list to offer full
+ * control of display. The 'list' value will place all of the paginated links in
+ * an unordered HTML list.
+ *
+ * The 'total' argument is the total amount of pages and is an integer. The
+ * 'current' argument is the current page number and is also an integer.
+ *
+ * An example of the 'base' argument is "http://example.com/all_posts.php%_%"
+ * and the '%_%' is required. The '%_%' will be replaced by the contents of in
+ * the 'format' argument. An example for the 'format' argument is "?page=%#%"
+ * and the '%#%' is also required. The '%#%' will be replaced with the page
+ * number.
+ *
+ * You can include the previous and next links in the list by setting the
+ * 'prev_next' argument to true, which it is by default. You can set the
+ * previous text, by using the 'prev_text' argument. You can set the next text
+ * by setting the 'next_text' argument.
+ *
+ * If the 'show_all' argument is set to true, then it will show all of the pages
+ * instead of a short list of the pages near the current page. By default, the
+ * 'show_all' is set to false and controlled by the 'end_size' and 'mid_size'
+ * arguments. The 'end_size' argument is how many numbers on either the start
+ * and the end list edges, by default is 1. The 'mid_size' argument is how many
+ * numbers to either side of current page, but not including current page.
+ *
+ * It is possible to add query vars to the link by using the 'add_args' argument
+ * and see {@link add_query_arg()} for more information.
+ *
  * @since 2.1.0
  *
- * @param unknown_type $args
- * @return unknown
+ * @param string|array $args Optional. Override defaults.
+ * @return array|string String of page links or array of page links.
  */
 function paginate_links( $args = '' ) {
         $defaults = array(
@@ -1460 +1574 @@
                 'prev_next' => true,
                 'prev_text' => __('&laquo; Previous'),
                 'next_text' => __('Next &raquo;'),
-                'end_size' => 1, // How many numbers on either end including the end
-                'mid_size' => 2, // How many numbers to either side of current not including current
+                'end_size' => 1,
+                'mid_size' => 2,
                 'type' => 'plain',
-                'add_args' => false // array of query args to aadd
+                'add_args' => false // array of query args to add
         );
 
         $args = wp_parse_args( $args, $defaults );
         extract($args, EXTR_SKIP);
 
         // Who knows what else people pass in $args
-        $total  = (int) $total;
+        $total = (int) $total;
         if ( $total < 2 )
                 return;
         $current  = (int) $current;