X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/7f1521bf193b382565eb753043c161f4cb3fcda7..53f4633144ed68c8b8fb5861f992b5489894a940:/wp-includes/author-template.php

diff --git a/wp-includes/author-template.php b/wp-includes/author-template.php
index 2e520f54..36d08bc8 100644
--- a/wp-includes/author-template.php
+++ b/wp-includes/author-template.php
@@ -15,10 +15,10 @@
  *
  * @since 1.5.0
  *
- * @uses $authordata The current author's DB object.
+ * @global object $authordata The current author's DB object.
  *
  * @param string $deprecated Deprecated.
- * @return string The author's display name.
+ * @return string|null The author's display name.
  */
 function get_the_author($deprecated = '') {
 	global $authordata;
@@ -53,7 +53,7 @@ function get_the_author($deprecated = '') {
  *
  * @param string $deprecated Deprecated.
  * @param string $deprecated_echo Deprecated. Use get_the_author(). Echo the string or return it.
- * @return string The author's display name, from get_the_author().
+ * @return string|null The author's display name, from get_the_author().
  */
 function the_author( $deprecated = '', $deprecated_echo = true ) {
 	if ( !empty( $deprecated ) )
@@ -70,7 +70,7 @@ function the_author( $deprecated = '', $deprecated_echo = true ) {
  *
  * @since 2.8.0
  *
- * @return string The author's display name.
+ * @return string|void The author's display name.
  */
 function get_the_modified_author() {
 	if ( $last_id = get_post_meta( get_post()->ID, '_edit_last', true) ) {
@@ -88,12 +88,12 @@ function get_the_modified_author() {
 }
 
 /**
- * Display the name of the author who last edited the current post.
+ * Display the name of the author who last edited the current post,
+ * if the author's ID is available.
  *
  * @since 2.8.0
  *
  * @see get_the_author()
- * @return string The author's display name, from get_the_modified_author().
  */
 function the_modified_author() {
 	echo get_the_modified_author();
@@ -103,11 +103,16 @@ function the_modified_author() {
  * Retrieve the requested data of the author of the current post.
  * @link https://codex.wordpress.org/Template_Tags/the_author_meta
  * @since 2.8.0
+ *
+ * @global object $authordata The current author's DB object.
+ *
  * @param string $field selects the field of the users record.
  * @param int $user_id Optional. User ID.
  * @return string The author's field from the current author's DB object.
  */
 function get_the_author_meta( $field = '', $user_id = false ) {
+	$original_user_id = $user_id;
+
 	if ( ! $user_id ) {
 		global $authordata;
 		$user_id = isset( $authordata->ID ) ? $authordata->ID : 0;
@@ -126,20 +131,24 @@ function get_the_author_meta( $field = '', $user_id = false ) {
 	 * The filter name is dynamic and depends on the $field parameter of the function.
 	 *
 	 * @since 2.8.0
+	 * @since 4.3.0 The `$original_user_id` parameter was added.
 	 *
-	 * @param string $value   The value of the metadata.
-	 * @param int    $user_id The user ID.
+	 * @param string   $value            The value of the metadata.
+	 * @param int      $user_id          The user ID for the value.
+	 * @param int|bool $original_user_id The original user ID, as passed to the function.
 	 */
-	return apply_filters( 'get_the_author_' . $field, $value, $user_id );
+	return apply_filters( 'get_the_author_' . $field, $value, $user_id, $original_user_id );
 }
 
 /**
- * Retrieve the requested data of the author of the current post.
+ * Outputs the field from the user's DB object. Defaults to current post's author.
+ *
  * @link https://codex.wordpress.org/Template_Tags/the_author_meta
+ *
  * @since 2.8.0
+ *
  * @param string $field selects the field of the users record.
  * @param int $user_id Optional. User ID.
- * @echo string The author's field from the current author's DB object.
  */
 function the_author_meta( $field = '', $user_id = false ) {
 	$author_meta = get_the_author_meta( $field, $user_id );
@@ -162,6 +171,9 @@ function the_author_meta( $field = '', $user_id = false ) {
  *
  * If the author has a home page set, return an HTML link, otherwise just return the
  * author's name.
+ *
+ * @return string|null An HTML link if the author's url exist in user meta,
+ *                     else the result of get_the_author().
  */
 function get_the_author_link() {
 	if ( get_the_author_meta('url') ) {
@@ -219,6 +231,9 @@ function the_author_posts() {
  *
  * @link https://codex.wordpress.org/Template_Tags/the_author_posts_link
  * @since 1.2.0
+ *
+ * @global object $authordata The current author's DB object.
+ *
  * @param string $deprecated Deprecated.
  */
 function the_author_posts_link($deprecated = '') {
@@ -226,8 +241,10 @@ function the_author_posts_link($deprecated = '') {
 		_deprecated_argument( __FUNCTION__, '2.1' );
 
 	global $authordata;
-	if ( !is_object( $authordata ) )
-		return false;
+	if ( ! is_object( $authordata ) ) {
+		return;
+	}
+
 	$link = sprintf(
 		'<a href="%1$s" title="%2$s" rel="author">%3$s</a>',
 		esc_url( get_author_posts_url( $authordata->ID, $authordata->user_nicename ) ),
@@ -249,7 +266,9 @@ function the_author_posts_link($deprecated = '') {
  * Retrieve the URL to the author page for the user with the ID provided.
  *
  * @since 2.1.0
- * @uses $wp_rewrite WP_Rewrite
+ *
+ * @global WP_Rewrite $wp_rewrite
+ *
  * @return string The URL to the author's page.
  */
 function get_author_posts_url($author_id, $author_nicename = '') {
@@ -291,6 +310,8 @@ function get_author_posts_url($author_id, $author_nicename = '') {
  *
  * @since 1.2.0
  *
+ * @global wpdb $wpdb
+ *
  * @param string|array $args {
  *     Optional. Array or string of default arguments.
  *
@@ -315,7 +336,7 @@ function get_author_posts_url($author_id, $author_nicename = '') {
  *     @type string $exclude       An array, comma-, or space-separated list of author IDs to exclude. Default empty.
  *     @type string $exclude       An array, comma-, or space-separated list of author IDs to include. Default empty.
  * }
- * @return null|string The output, if echo is set to false. Otherwise null.
+ * @return string|void The output, if echo is set to false.
  */
 function wp_list_authors( $args = '' ) {
 	global $wpdb;
@@ -422,6 +443,9 @@ function wp_list_authors( $args = '' ) {
  * Checks to see if more than one author has published posts.
  *
  * @since 3.2.0
+ *
+ * @global wpdb $wpdb
+ *
  * @return bool Whether or not we have more than one author
  */
 function is_multi_author() {