WordPress.org

Make WordPress Core

Changeset 46223


Ignore:
Timestamp:
09/21/2019 10:01:05 AM (8 weeks ago)
Author:
johnbillion
Message:

Docs: Improve the docs for comment counting related functions.

See #47110, #48093

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/comment.php

    r46178 r46223  
    355355
    356356/**
    357  * The amount of comments in a post or total comments.
    358  *
    359  * A lot like wp_count_comments(), in that they both return comment stats (albeit with different types).
    360  * The wp_count_comments() actually caches, but this function does not.
     357 * Retrieves the total comment counts for the whole site or a single post.
     358 *
     359 * Unlike wp_count_comments(), this function always returns the live comment counts without caching.
    361360 *
    362361 * @since 2.0.0
     
    364363 * @global wpdb $wpdb WordPress database abstraction object.
    365364 *
    366  * @param int $post_id Optional. Comment amount in post if > 0, else total comments blog wide.
    367  * @return array The amount of spam, approved, awaiting moderation, and total comments.
     365 * @param int $post_id Optional. Restrict the comment counts to the given post. Default 0, which indicates that
     366 *                     comment counts for the whole site will be retrieved.
     367 * @return array() {
     368 *     The number of comments keyed by their status.
     369 *
     370 *     @type int|string $approved            The number of approved comments.
     371 *     @type int|string $awaiting_moderation The number of comments awaiting moderation (a.k.a. pending).
     372 *     @type int|string $spam                The number of spam comments.
     373 *     @type int|string $trash               The number of trashed comments.
     374 *     @type int|string $post-trashed        The number of comments for posts that are in the trash.
     375 *     @type int        $total_comments      The total number of non-trashed comments, including spam.
     376 *     @type int        $all                 The total number of pending or approved comments.
     377 * }
    368378 */
    369379function get_comment_count( $post_id = 0 ) {
     
    12971307
    12981308/**
    1299  * Retrieve total comments for blog or single post.
    1300  *
    1301  * The properties of the returned object contain the 'moderated', 'approved',
    1302  * and spam comments for either the entire blog or single post. Those properties
    1303  * contain the amount of comments that match the status. The 'total_comments'
    1304  * property contains the integer of total comments.
     1309 * Retrieves the total comment counts for the whole site or a single post.
    13051310 *
    13061311 * The comment stats are cached and then retrieved, if they already exist in the
    13071312 * cache.
    13081313 *
     1314 * @see get_comment_count() Which handles fetching the live comment counts.
     1315 *
    13091316 * @since 2.5.0
    13101317 *
    1311  * @param int $post_id Optional. Post ID.
    1312  * @return object|array Comment stats.
     1318 * @param int $post_id Optional. Restrict the comment counts to the given post. Default 0, which indicates that
     1319 *                     comment counts for the whole site will be retrieved.
     1320 * @return stdClass {
     1321 *     The number of comments keyed by their status.
     1322 *
     1323 *     @type int|string $approved       The number of approved comments.
     1324 *     @type int|string $moderated      The number of comments awaiting moderation (a.k.a. pending).
     1325 *     @type int|string $spam           The number of spam comments.
     1326 *     @type int|string $trash          The number of trashed comments.
     1327 *     @type int|string $post-trashed   The number of comments for posts that are in the trash.
     1328 *     @type int        $total_comments The total number of non-trashed comments, including spam.
     1329 *     @type int        $all            The total number of pending or approved comments.
     1330 * }
    13131331 */
    13141332function wp_count_comments( $post_id = 0 ) {
     
    13161334
    13171335    /**
    1318      * Filters the comments count for a given post.
     1336     * Filters the comments count for a given post or the whole site.
    13191337     *
    13201338     * @since 2.7.0
    13211339     *
    1322      * @param array $count   An empty array.
    1323      * @param int   $post_id The post ID.
     1340     * @param array|stdClass $count   An empty array or an object containing comment counts.
     1341     * @param int            $post_id The post ID. Can be 0 to represent the whole site.
    13241342     */
    13251343    $filtered = apply_filters( 'wp_count_comments', array(), $post_id );
Note: See TracChangeset for help on using the changeset viewer.