WordPress.org
Get WordPress

Make WordPress Core

Ticket #25229: author-template.patch

File author-template.patch, 14.2 KB (added by Frank Klein, 11 years ago)

Adds filter documentation for wp-includes/author-template.php. Also updates outdated function documentation.

  • wp-includes/author-template.php

     
    1111 */
    1212
    1313/**
    14  * Retrieve the author of the current post.
     14 * Retrieve the display name of the author of the current post.
    1515 *
    16  * @since 1.5
    17  * @uses $authordata The current author's DB object.
    18  * @uses apply_filters() Calls 'the_author' hook on the author display name.
     16 * @global $authordata
    1917 *
     18 * @since 1.5.0
     19 *
    2020 * @param string $deprecated Deprecated.
    2121 * @return string The author's display name.
    2222 */
    … …  
    2626        if ( !empty( $deprecated ) )
    2727                _deprecated_argument( __FUNCTION__, '2.1' );
    2828
     29        /**
     30         * The display name of the current post's author.
     31         *
     32         * @since 2.9.0
     33         *
     34         * @param string $authordata->display_name The author's display name.
     35         */
    2936        return apply_filters('the_author', is_object($authordata) ? $authordata->display_name : null);
    3037}
    3138
    3239/**
    33  * Display the name of the author of the current post.
     40 * Display the display name of the author of the current post.
    3441 *
    3542 * The behavior of this function is based off of old functionality predating
    3643 * get_the_author(). This function is not deprecated, but is designed to echo
    … …  
    4047 * The normal, expected behavior of this function is to echo the author and not
    4148 * return it. However, backwards compatibility has to be maintained.
    4249 *
    43  * @since 0.71
    4450 * @see get_the_author()
    4551 * @link http://codex.wordpress.org/Template_Tags/the_author
    4652 *
     53 * @since 0.71
     54 *
    4755 * @param string $deprecated Deprecated.
    4856 * @param string $deprecated_echo Deprecated. Use get_the_author(). Echo the string or return it.
    49  * @return string The author's display name, from get_the_author().
     57 * @return string The author's display name.
    5058 */
    5159function the_author( $deprecated = '', $deprecated_echo = true ) {
    5260        if ( !empty( $deprecated ) )
    … …  
    5967}
    6068
    6169/**
    62  * Retrieve the author who last edited the current post.
     70 * Retrieve the display name of the author who last edited the current post.
    6371 *
    64  * @since 2.8
    65  * @uses $post The current post's DB object.
    66  * @uses get_post_meta() Retrieves the ID of the author who last edited the current post.
    67  * @uses get_userdata() Retrieves the author's DB object.
    68  * @uses apply_filters() Calls 'the_modified_author' hook on the author display name.
     72 * @see get_post_meta()
     73 * @see get_post()
     74 * @see get_userdata()
     75 *
     76 * @since 2.8.0
     77 *
    6978 * @return string The author's display name.
    7079 */
    7180function get_the_modified_author() {
    7281        if ( $last_id = get_post_meta( get_post()->ID, '_edit_last', true) ) {
    7382                $last_user = get_userdata($last_id);
     83
     84                /**
     85                * The display name of author who last edited the current post.
     86                *
     87                * @since 2.8.0
     88                *
     89                * @param string $last_user->display_name The author's display name.
     90                */
    7491                return apply_filters('the_modified_author', $last_user->display_name);
    7592        }
    7693}
    7794
    7895/**
    79  * Display the name of the author who last edited the current post.
     96 * Display the display name of the author who last edited the current post.
    8097 *
    81  * @since 2.8
    82  * @see get_the_author()
    83  * @return string The author's display name, from get_the_modified_author().
     98 * @see get_the_modified_author
     99 *
     100 * @since 2.8.0
     101 *
     102 * @return void
    84103 */
    85104function the_modified_author() {
    86105        echo get_the_modified_author();
    87106}
    88107
    89108/**
    90  * Retrieve the requested data of the author of the current post.
    91  * @link http://codex.wordpress.org/Template_Tags/the_author_meta
     109 * Retrieve the requested metadata for the author of the current post or the author with the specified ID.
     110 *
     111 * @see get_userdata()
     112 * @link http://codex.wordpress.org/Function_Reference/get_the_author_meta
     113 *
     114 * @global $authordata
     115 *
    92116 * @since 2.8.0
    93  * @uses $authordata The current author's DB object (if $user_id not specified).
    94  * @param string $field selects the field of the users record.
    95  * @param int $user_id Optional. User ID.
    96  * @return string The author's field from the current author's DB object.
     117 *
     118 * @param string $field The name of the metadata to retrieve.
     119 * @param int $user_id Optional. The ID of a user. Defaults to the current user.
     120 * @return string The value of the metadata or empty string.
    97121 */
    98122function get_the_author_meta( $field = '', $user_id = false ) {
    99123        if ( ! $user_id ) {
    … …  
    108132
    109133        $value = isset( $authordata->$field ) ? $authordata->$field : '';
    110134
     135        /**
     136         * The value of the requested user metadata.
     137         *
     138         * @since 2.8.0
     139         *
     140         * @param string The name of the metadata.
     141         * @param string The value of the metadata.
     142         * @param int The user ID.
     143         */
    111144        return apply_filters( 'get_the_author_' . $field, $value, $user_id );
    112145}
    113146
    114147/**
    115  * Retrieve the requested data of the author of the current post.
     148 * Display the requested metadata for the author of the current post or the author with the specified ID.
     149 *
     150 * @see get_the_author_meta()
    116151 * @link http://codex.wordpress.org/Template_Tags/the_author_meta
     152 *
    117153 * @since 2.8.0
    118  * @param string $field selects the field of the users record.
    119  * @param int $user_id Optional. User ID.
    120  * @echo string The author's field from the current author's DB object.
     154 *
     155 * @param string $field The name of the metadata to display.
     156 * @param int $user_id Optional. The ID of a user. Defaults to the current user.
     157 * @return void
    121158 */
    122159function the_author_meta($field = '', $user_id = false) {
     160        /**
     161         * The value of the requested user metadata.
     162         *
     163         * @since 2.8.0
     164         *
     165         * @param string The name of the metadata.
     166         * @param string The value of the metadata.
     167         * @param int The user ID.
     168         */
    123169        echo apply_filters('the_author_' . $field, get_the_author_meta($field, $user_id), $user_id);
    124170}
    125171
    126172/**
    127  * Retrieve either author's link or author's name.
     173 * Retrieve the author's homepage link or the author's display name.
    128174 *
    129  * If the author has a home page set, return an HTML link, otherwise just return the
    130  * author's name.
     175 * If the author has a home page set, return an HTML link, otherwise just return the author's display name.
    131176 *
    132  * @uses get_the_author_meta()
    133  * @uses get_the_author()
     177 * @see get_the_author_meta()
     178 * @see get_the_author()
     179 *
     180 * @since 2.1.0
     181 *
     182 * @return string HTML link to the author's homepage or the author's display name.
    134183 */
    135184function get_the_author_link() {
    136185        if ( get_the_author_meta('url') ) {
    … …  
    141190}
    142191
    143192/**
    144  * Display either author's link or author's name.
     193 * Display the author's homepage link or the author's display name.
    145194 *
    146  * If the author has a home page set, echo an HTML link, otherwise just echo the
    147  * author's name.
     195 * If the author has a home page set, display an HTML link, otherwise just display the author's display name.
    148196 *
     197 * @see get_the_author_link()
    149198 * @link http://codex.wordpress.org/Template_Tags/the_author_link
    150  * @since 2.1
    151  * @uses get_the_author_link()
     199 *
     200 * @since 2.1.0
     201 *
     202 * @return void
    152203 */
    153204function the_author_link() {
    154205        echo get_the_author_link();
    … …  
    157208/**
    158209 * Retrieve the number of posts by the author of the current post.
    159210 *
    160  * @since 1.5
    161  * @uses $post The current post in the Loop's DB object.
    162  * @uses count_user_posts()
     211 * @see count_user_posts()
     212 *
     213 * @since 1.5.0
     214 *
    163215 * @return int The number of posts by the author.
    164216 */
    165217function get_the_author_posts() {
    … …  
    169221/**
    170222 * Display the number of posts by the author of the current post.
    171223 *
    172  * @link http://codex.wordpress.org/Template_Tags/the_author_posts
     224 * @see get_the_author_posts()
     225 *
    173226 * @since 0.71
    174  * @uses get_the_author_posts() Echoes returned value from function.
     227 *
     228 * @return void
    175229 */
    176230function the_author_posts() {
    177231        echo get_the_author_posts();
    … …  
    180234/**
    181235 * Display an HTML link to the author page of the author of the current post.
    182236 *
    183  * Does just echo get_author_posts_url() function, like the others do. The
    184  * reason for this, is that another function is used to help in printing the
    185  * link to the author's posts.
     237 * @see get_author_posts_url()
     238 * @see get_the_author()
     239 * @link http://codex.wordpress.org/Template_Tags/the_author_posts_link
    186240 *
    187  * @link http://codex.wordpress.org/Template_Tags/the_author_posts_link
     241 * @global $authordata
     242 *
    188243 * @since 1.2.0
    189  * @uses $authordata The current author's DB object.
    190  * @uses get_author_posts_url()
    191  * @uses get_the_author()
     244 *
    192245 * @param string $deprecated Deprecated.
     246 * @return void
    193247 */
    194248function the_author_posts_link($deprecated = '') {
    195249        if ( !empty( $deprecated ) )
    … …  
    204258                esc_attr( sprintf( __( 'Posts by %s' ), get_the_author() ) ),
    205259                get_the_author()
    206260        );
     261
     262        /**
     263         * The link to the author page of the author of the current post.
     264         *
     265         * @since 2.9.0
     266         *
     267         * @param string HTML link
     268         */
    207269        echo apply_filters( 'the_author_posts_link', $link );
    208270}
    209271
    210272/**
    211273 * Retrieve the URL to the author page for the user with the ID provided.
    212274 *
     275 * @see get_author_permastruct()
     276 * @see get_userdata()
     277 *
     278 * @global $wp_rewrite
     279 *
    213280 * @since 2.1.0
    214  * @uses $wp_rewrite WP_Rewrite
     281 *
     282 * @param int $author_id The ID of a user.
     283 * @param string $author_nicename Optional. The author's nice name.
    215284 * @return string The URL to the author's page.
    216285 */
    217286function get_author_posts_url($author_id, $author_nicename = '') {
    … …  
    232301                $link = home_url( user_trailingslashit( $link ) );
    233302        }
    234303
     304        /**
     305         * The URL to the author's page.
     306         *
     307         * @since 2.1.0
     308         *
     309         * @param string $link The URL to the author's page.
     310         * @param int $author_id The ID of a user.
     311         * @param string $author_nicename Optional. The author's nice name.
     312         */
    235313        $link = apply_filters('author_link', $link, $author_id, $author_nicename);
    236314
    237315        return $link;
    238316}
    239317
    240318/**
    241  * List all the authors of the blog, with several options available.
     319 * Display or return a list of all the authors of the blog.
    242320 *
    243  * <ul>
    244  * <li>optioncount (boolean) (false): Show the count in parenthesis next to the
    245  * author's name.</li>
    246  * <li>exclude_admin (boolean) (true): Exclude the 'admin' user that is
    247  * installed by default.</li>
    248  * <li>show_fullname (boolean) (false): Show their full names.</li>
    249  * <li>hide_empty (boolean) (true): Don't show authors without any posts.</li>
    250  * <li>feed (string) (''): If isn't empty, show links to author's feeds.</li>
    251  * <li>feed_image (string) (''): If isn't empty, use this image to link to
    252  * feeds.</li>
    253  * <li>echo (boolean) (true): Set to false to return the output, instead of
    254  * echoing.</li>
    255  * <li>style (string) ('list'): Whether to display list of authors in list form
    256  * or as a string.</li>
    257  * <li>html (bool) (true): Whether to list the items in html form or plaintext.
    258  * </li>
    259  * </ul>
     321 * The list can be displayed or returned as an unordered HTML list or as a comma-separated string.
    260322 *
     323 * @see get_users()
     324 * @see get_user_data()
    261325 * @link http://codex.wordpress.org/Template_Tags/wp_list_authors
     326 *
     327 * @global $wpdb
     328 *
    262329 * @since 1.2.0
    263  * @param array $args The argument array.
    264  * @return null|string The output, if echo is set to false.
     330 *
     331 * @param array $args {
     332 *      An array of arguments. Optional.
     333 *      @type string 'orderby'       What columns to sort authors by, comma-separated.
     334 *                                   Default 'name'. @see WP_User_Query for accepted args.
     335 *      @type string 'order'         How to sort retrieved authors.
     336 *                                   Default 'ASC'. @see WP_User_Query for accepted args.
     337 *      @type int    'number'        The number of authors to return.
     338 *                                   Default blank. Accepts a number.
     339 *      @type bool   'optioncount'   Whether to show the number of posts next to the name of each author in parenthesis.
     340 *                                   Default 'false'. Accepts 'true' or 'false'.
     341 *      @type bool   'exclude_admin' Whether to exclude the author with the 'admin' display name.
     342 *                                   Default 'true'. Accepts 'true' or 'false'.
     343 *      @type bool   'show_fullname' Whether to display the full names of the authors.
     344 *                                   Default 'false'. Accepts 'true' or 'false'.
     345 *      @type bool   'hide_empty'    Whether to hide authors without any posts.
     346 *                                   Default 'true'. Accepts 'true' or 'false'.
     347 *      @type string 'feed'          Whether to show a link to the author's feed.
     348 *                                   Default blank. Any other value will display the feed.
     349 *      @type string 'feed_image'    URL to the feed image displayed as part of the feed link.
     350 *                                   Default blank. Accepts a URL.
     351 *      @type string 'feed_type'     Unused argument.
     352 *                                   Default blank.
     353 *      @type bool   'echo'          Whether to display the list or return it.
     354 *                                   Default 'true'. Accepts 'true' or 'false'.
     355 *      @type string 'style'         Whether to list the items as an ordered list or as a comma separated list.
     356 *                                   Default 'list'. Any other value will produce a comma separated list.
     357 *      @type bool   'html'          Whether to list the items in HTML or plain text format.
     358 *                                   Default 'true'. Accepts 'true' or 'false'.
     359 * }
     360 *
     361 * @return void|string Returns nothing if 'echo' is set to true, else returns the list.
    265362 */
    266363function wp_list_authors($args = '') {
    267364        global $wpdb;
    … …  
    362459}
    363460
    364461/**
    365  * Does this site have more than one author
     462 * Does this site have more than one author.
    366463 *
    367464 * Checks to see if more than one author has published posts.
    368465 *
     466 * @global $wpdb
     467 *
    369468 * @since 3.2.0
    370  * @return bool Whether or not we have more than one author
     469 *
     470 * @return bool Whether or not we have more than one author.
    371471 */
    372472function is_multi_author() {
    373473        global $wpdb;
    … …  
    378478                set_transient( 'is_multi_author', $is_multi_author );
    379479        }
    380480
     481        /**
     482         * Whether the site has more than one author with published posts.
     483         *
     484         * @since 3.2.0
     485         *
     486         * @param bool $is_multi_author Is there more than one author.
     487         */
    381488        return apply_filters( 'is_multi_author', (bool) $is_multi_author );
    382489}
    383490
    384491/**
    385492 * Helper function to clear the cache for number of authors.
    386493 *
    387  * @private
     494 * @access private
     495 *
     496 * @since 3.2.0
     497 *
     498 * @return void
    388499 */
    389500function __clear_multi_author_cache() {
    390501        delete_transient( 'is_multi_author' );
    391502}
    392 add_action('transition_post_status', '__clear_multi_author_cache');
     503add_action('transition_post_status', '__clear_multi_author_cache');
     504 No newline at end of file