get_comments_number
get_comments_number is a filter on the number returned by the get_comments_number() function. Note that this is somewhat related to the comments_number hook, which filters the text output of the comments_number() function.
Context:
File: wp-includes/comment-functions.php
function get_comments_number( $comment_id ) {
global $wpdb, $comment_count_cache;
$comment_id = (int) $comment_id;
if (!isset($comment_count_cache[$comment_id]))
$comment_count_cache[$comment_id] = $wpdb->get_var("SELECT COUNT(*) FROM $wpdb->comments WHERE comment_post_ID = '$comment_id' AND comment_approved = '1'");
return apply_filters('get_comments_number', $comment_count_cache[$comment_id]);
}
This hook is a filter which means that information is passed through it, and then used by WordPress. Your function needs to accept that information, and return it. Using add_filter('get_comments_number', 'your_function'); helps you to remember this distinction. When you are passing an ID, it is assumed that you will return the ID as it was given to you. With filters that pass strings or arrays, you may manipulate the information before passing it along.