X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/f5fcdc7994bb67cce809bc4777944ae8b7fad4a4..refs/tags/wordpress-4.3:/wp-includes/post-template.php

diff --git a/wp-includes/post-template.php b/wp-includes/post-template.php
index 2a6569f2..1b4901cc 100644
--- a/wp-includes/post-template.php
+++ b/wp-includes/post-template.php
@@ -22,7 +22,7 @@ function the_ID() {
  *
  * @since 2.1.0
  *
- * @return int|bool The ID of the current item in the WordPress Loop. False if $post is not set.
+ * @return int|false The ID of the current item in the WordPress Loop. False if $post is not set.
  */
 function get_the_ID() {
 	$post = get_post();
@@ -35,11 +35,11 @@ function get_the_ID() {
  * @since 0.71
  *
  * @param string $before Optional. Content to prepend to the title.
- * @param string $after Optional. Content to append to the title.
- * @param bool $echo Optional, default to true.Whether to display or return.
- * @return null|string Null on no title. String if $echo parameter is false.
+ * @param string $after  Optional. Content to append to the title.
+ * @param bool   $echo   Optional, default to true.Whether to display or return.
+ * @return string|void String if $echo parameter is false.
  */
-function the_title($before = '', $after = '', $echo = true) {
+function the_title( $before = '', $after = '', $echo = true ) {
 	$title = get_the_title();
 
 	if ( strlen($title) == 0 )
@@ -73,7 +73,7 @@ function the_title($before = '', $after = '', $echo = true) {
  *     @type bool    $echo   Whether to echo or return the title. Default true for echo.
  *     @type WP_Post $post   Current post object to retrieve the title for.
  * }
- * @return string|null Null on failure or display. String when echo is false.
+ * @return string|void String when echo is false.
  */
 function the_title_attribute( $args = '' ) {
 	$defaults = array( 'before' => '', 'after' =>  '', 'echo' => true, 'post' => get_post() );
@@ -237,6 +237,12 @@ function the_content( $more_link_text = null, $strip_teaser = false) {
  *
  * @since 0.71
  *
+ * @global int   $page
+ * @global int   $more
+ * @global bool  $preview
+ * @global array $pages
+ * @global int   $multipage
+ *
  * @param string $more_link_text Optional. Content for when there is more text.
  * @param bool $strip_teaser Optional. Strip teaser content before the more text. Default is false.
  * @return string
@@ -521,6 +527,9 @@ function body_class( $class = '' ) {
  *
  * @since 2.8.0
  *
+ * @global WP_Query $wp_query
+ * @global wpdb     $wpdb
+ *
  * @param string|array $class One or more classes to add to the class list.
  * @return array Array of classes.
  */
@@ -726,7 +735,7 @@ function get_body_class( $class = '' ) {
  *
  * @since 2.7.0
  *
- * @param int|WP_Post $post An optional post. Global $post used if not provided.
+ * @param int|WP_Post|null $post An optional post. Global $post used if not provided.
  * @return bool false if a password is not required or the correct password cookie is present, true otherwise.
  */
 function post_password_required( $post = null ) {
@@ -760,6 +769,11 @@ function post_password_required( $post = null ) {
  *
  * @since 1.2.0
  *
+ * @global int $page
+ * @global int $numpages
+ * @global int $multipage
+ * @global int $more
+ *
  * @param string|array $args {
  *     Optional. Array or string of default arguments.
  *
@@ -782,6 +796,8 @@ function post_password_required( $post = null ) {
  * @return string Formatted output in HTML.
  */
 function wp_link_pages( $args = '' ) {
+	global $page, $numpages, $multipage, $more;
+
 	$defaults = array(
 		'before'           => '<p>' . __( 'Pages:' ),
 		'after'            => '</p>',
@@ -806,8 +822,6 @@ function wp_link_pages( $args = '' ) {
 	 */
 	$r = apply_filters( 'wp_link_pages_args', $params );
 
-	global $page, $numpages, $multipage, $more;
-
 	$output = '';
 	if ( $multipage ) {
 		if ( 'number' == $r['next_or_number'] ) {
@@ -877,6 +891,8 @@ function wp_link_pages( $args = '' ) {
  * @since 3.1.0
  * @access private
  *
+ * @global WP_Rewrite $wp_rewrite
+ *
  * @param int $i Page number.
  * @return string Link.
  */
@@ -921,7 +937,7 @@ function _wp_link_page( $i ) {
  * @since 1.5.0
  *
  * @param string $key Meta data key name.
- * @return bool|string|array Array of values or single value, if only one element exists. False will be returned if key does not exist.
+ * @return false|string|array Array of values or single value, if only one element exists. False will be returned if key does not exist.
  */
 function post_custom( $key = '' ) {
 	$custom = get_post_custom();
@@ -974,6 +990,7 @@ function the_meta() {
  *
  * @since 2.1.0
  * @since 4.2.0 The `$value_field` argument was added.
+ * @since 4.3.0 The `$class` argument was added.
  *
  * @param array|string $args {
  *     Optional. Array or string of arguments to generate a pages drop-down element.
@@ -986,6 +1003,7 @@ function the_meta() {
  *     @type string       $name                  Value for the 'name' attribute of the select element.
  *                                               Default 'page_id'.
  *     @type string       $id                    Value for the 'id' attribute of the select element.
+ *     @type string       $class                 Value for the 'class' attribute of the select element. Default: none.
  *                                               Defaults to the value of `$name`.
  *     @type string       $show_option_none      Text to display for showing no pages. Default empty (does not display).
  *     @type string       $show_option_no_change Text to display for "no change" option. Default empty (does not display).
@@ -1000,6 +1018,7 @@ function wp_dropdown_pages( $args = '' ) {
 		'depth' => 0, 'child_of' => 0,
 		'selected' => 0, 'echo' => 1,
 		'name' => 'page_id', 'id' => '',
+		'class' => '',
 		'show_option_none' => '', 'show_option_no_change' => '',
 		'option_none_value' => '',
 		'value_field' => 'ID',
@@ -1015,7 +1034,12 @@ function wp_dropdown_pages( $args = '' ) {
 	}
 
 	if ( ! empty( $pages ) ) {
-		$output = "<select name='" . esc_attr( $r['name'] ) . "' id='" . esc_attr( $r['id'] ) . "'>\n";
+		$class = '';
+		if ( ! empty( $r['class'] ) ) {
+			$class = " class='" . esc_attr( $r['class'] ) . "'";
+		}
+
+		$output = "<select name='" . esc_attr( $r['name'] ) . "'" . $class . " id='" . esc_attr( $r['id'] ) . "'>\n";
 		if ( $r['show_option_no_change'] ) {
 			$output .= "\t<option value=\"-1\">" . $r['show_option_no_change'] . "</option>\n";
 		}
@@ -1048,6 +1072,8 @@ function wp_dropdown_pages( $args = '' ) {
  *
  * @see get_pages()
  *
+ * @global WP_Query $wp_query
+ *
  * @param array|string $args {
  *     Array or string of arguments. Optional.
  *
@@ -1074,7 +1100,7 @@ function wp_dropdown_pages( $args = '' ) {
  *                                will not be wrapped with unordered list `<ul>` tags. Default 'Pages'.
  *     @type Walker $walker       Walker instance to use for listing pages. Default empty (Walker_Page).
  * }
- * @return string HTML list of pages.
+ * @return string|void HTML list of pages.
  */
 function wp_list_pages( $args = '' ) {
 	$defaults = array(
@@ -1172,7 +1198,7 @@ function wp_list_pages( $args = '' ) {
  *     @type int|bool|string $show_home   Whether to display the link to the home page. Can just enter the text
  *                                        you'd like shown for the home link. 1|true defaults to 'Home'.
  * }
- * @return string html menu
+ * @return string|void HTML menu
  */
 function wp_page_menu( $args = array() ) {
 	$defaults = array('sort_column' => 'menu_order, post_title', 'menu_class' => 'menu', 'echo' => true, 'link_before' => '', 'link_after' => '');
@@ -1249,9 +1275,14 @@ function wp_page_menu( $args = array() ) {
  *
  * @uses Walker_Page to create HTML list content.
  * @since 2.1.0
- * @see Walker_Page::walk() for parameters and return description.
+ *
+ * @param array $pages
+ * @param int   $depth
+ * @param int   $current_page
+ * @param array $r
+ * @return string
  */
-function walk_page_tree($pages, $depth, $current_page, $r) {
+function walk_page_tree( $pages, $depth, $current_page, $r ) {
 	if ( empty($r['walker']) )
 		$walker = new Walker_Page;
 	else
@@ -1272,6 +1303,8 @@ function walk_page_tree($pages, $depth, $current_page, $r) {
  * @uses Walker_PageDropdown to create HTML dropdown content.
  * @since 2.1.0
  * @see Walker_PageDropdown::walk() for parameters and return description.
+ *
+ * @return string
  */
 function walk_page_dropdown_tree() {
 	$args = func_get_args();
@@ -1310,8 +1343,8 @@ class Walker_Page extends Walker {
 	 * @since 2.1.0
 	 *
 	 * @param string $output Passed by reference. Used to append additional content.
-	 * @param int $depth Depth of page. Used for padding.
-	 * @param array $args
+	 * @param int    $depth  Depth of page. Used for padding.
+	 * @param array  $args
 	 */
 	public function start_lvl( &$output, $depth = 0, $args = array() ) {
 		$indent = str_repeat("\t", $depth);
@@ -1323,8 +1356,8 @@ class Walker_Page extends Walker {
 	 * @since 2.1.0
 	 *
 	 * @param string $output Passed by reference. Used to append additional content.
-	 * @param int $depth Depth of page. Used for padding.
-	 * @param array $args
+	 * @param int    $depth  Depth of page. Used for padding.
+	 * @param array  $args
 	 */
 	public function end_lvl( &$output, $depth = 0, $args = array() ) {
 		$indent = str_repeat("\t", $depth);
@@ -1335,11 +1368,11 @@ class Walker_Page extends Walker {
 	 * @see Walker::start_el()
 	 * @since 2.1.0
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
-	 * @param object $page Page data object.
-	 * @param int $depth Depth of page. Used for padding.
-	 * @param int $current_page Page ID.
-	 * @param array $args
+	 * @param string $output       Passed by reference. Used to append additional content.
+	 * @param object $page         Page data object.
+	 * @param int    $depth        Depth of page. Used for padding.
+	 * @param int    $current_page Page ID.
+	 * @param array  $args
 	 */
 	public function start_el( &$output, $page, $depth = 0, $args = array(), $current_page = 0 ) {
 		if ( $depth ) {
@@ -1385,6 +1418,7 @@ class Walker_Page extends Walker {
 		$css_classes = implode( ' ', apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_page ) );
 
 		if ( '' === $page->post_title ) {
+			/* translators: %d: ID of a post */
 			$page->post_title = sprintf( __( '#%d (no title)' ), $page->ID );
 		}
 
@@ -1419,8 +1453,8 @@ class Walker_Page extends Walker {
 	 *
 	 * @param string $output Passed by reference. Used to append additional content.
 	 * @param object $page Page data object. Not used.
-	 * @param int $depth Depth of page. Not Used.
-	 * @param array $args
+	 * @param int    $depth Depth of page. Not Used.
+	 * @param array  $args
 	 */
 	public function end_el( &$output, $page, $depth = 0, $args = array() ) {
 		$output .= "</li>\n";
@@ -1458,8 +1492,8 @@ class Walker_PageDropdown extends Walker {
 	 * @param object $page   Page data object.
 	 * @param int    $depth  Depth of page in reference to parent pages. Used for padding.
 	 * @param array  $args   Uses 'selected' argument for selected page to set selected HTML attribute for option
-	 *              element. Uses 'value_field' argument to fill "value" attribute. See {@see wp_dropdown_pages()}.
-	 * @param int $id
+	 *                       element. Uses 'value_field' argument to fill "value" attribute. See {@see wp_dropdown_pages()}.
+	 * @param int    $id
 	 */
 	public function start_el( &$output, $page, $depth = 0, $args = array(), $id = 0 ) {
 		$pad = str_repeat('&nbsp;', $depth * 3);
@@ -1475,6 +1509,7 @@ class Walker_PageDropdown extends Walker {
 
 		$title = $page->post_title;
 		if ( '' === $title ) {
+			/* translators: %d: ID of a post */
 			$title = sprintf( __( '#%d (no title)' ), $page->ID );
 		}
 
@@ -1680,10 +1715,7 @@ function is_page_template( $template = '' ) {
 		}
 	}
 
-	if ( 'default' == $template && ! $page_template )
-		return true;
-
-	return false;
+	return ( 'default' === $template && ! $page_template );
 }
 
 /**
@@ -1692,7 +1724,7 @@ function is_page_template( $template = '' ) {
  * @since 3.4.0
  *
  * @param int $post_id Optional. The page ID to check. Defaults to the current post, when used in the loop.
- * @return string|bool Page template filename. Returns an empty string when the default page template
+ * @return string|false Page template filename. Returns an empty string when the default page template
  * 	is in use. Returns false if the post is not a page.
  */
 function get_page_template_slug( $post_id = null ) {
@@ -1711,8 +1743,8 @@ function get_page_template_slug( $post_id = null ) {
  * @since 2.6.0
  *
  * @param int|object $revision Revision ID or revision object.
- * @param bool $link Optional, default is true. Link to revisions's page?
- * @return string i18n formatted datetimestamp or localized 'Current Revision'.
+ * @param bool       $link     Optional, default is true. Link to revisions's page?
+ * @return string|false i18n formatted datetimestamp or localized 'Current Revision'.
  */
 function wp_post_revision_title( $revision, $link = true ) {
 	if ( !$revision = get_post( $revision ) )
@@ -1746,8 +1778,8 @@ function wp_post_revision_title( $revision, $link = true ) {
  * @since 3.6.0
  *
  * @param int|object $revision Revision ID or revision object.
- * @param bool $link Optional, default is true. Link to revisions's page?
- * @return string gravatar, user, i18n formatted datetimestamp or localized 'Current Revision'.
+ * @param bool       $link     Optional, default is true. Link to revisions's page?
+ * @return string|false gravatar, user, i18n formatted datetimestamp or localized 'Current Revision'.
  */
 function wp_post_revision_title_expanded( $revision, $link = true ) {
 	if ( !$revision = get_post( $revision ) )
@@ -1796,7 +1828,6 @@ function wp_post_revision_title_expanded( $revision, $link = true ) {
  *
  * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is global $post.
  * @param string      $type    'all' (default), 'revision' or 'autosave'
- * @return null
  */
 function wp_list_post_revisions( $post_id = 0, $type = 'all' ) {
 	if ( ! $post = get_post( $post_id ) )