From 223a2c7138e8453f2e874d3c6e7fd8502cfd4d6e Mon Sep 17 00:00:00 2001
From: Drew Jaynes <info@drewapicture.com>
Date: Tue, 26 Nov 2013 04:10:09 +0000
Subject: [PATCH] Inline documentation for the following filter hooks in
 wp-includes/pluggable.php: * `comment_notification_recipients` *
 `comment_notification_notify_author`

Also removes some generic `@uses` tags from various related doc blocks.

Props markjaquith.
Fixes #25699.

Built from https://develop.svn.wordpress.org/trunk@26388


git-svn-id: http://core.svn.wordpress.org/trunk@26288 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/comment.php   |  9 ---------
 wp-includes/pluggable.php | 34 +++++++++++++++++++++++-----------
 2 files changed, 23 insertions(+), 20 deletions(-)

diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index e48197c39a..26e535aca7 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -1378,15 +1378,6 @@ function wp_throttle_comment_flood($block, $time_lastcomment, $time_newcomment)
  *
  * @since 1.5.0
  * @param array $commentdata Contains information on the comment.
- * @uses apply_filters()
- * @uses wp_get_comment_status()
- * @uses wp_filter_comment()
- * @uses wp_allow_comment()
- * @uses wp_insert_comment()
- * @uses do_action()
- * @uses wp_notify_moderator()
- * @uses get_option()
- * @uses wp_notify_postauthor()
  * @return int The ID of the comment after adding.
  */
 function wp_new_comment( $commentdata ) {
diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php
index 5028f5deb7..aca94f3633 100644
--- a/wp-includes/pluggable.php
+++ b/wp-includes/pluggable.php
@@ -1006,16 +1006,6 @@ if ( ! function_exists('wp_notify_postauthor') ) :
  *
  * @param int $comment_id Comment ID
  * @param string $deprecated Not used
- * @uses get_comment()
- * @uses get_post()
- * @uses get_userdata()
- * @uses apply_filters()
- * @uses wp_specialchars_decode()
- * @uses get_option()
- * @uses __()
- * @uses get_permalink()
- * @uses admin_url()
- * @uses wp_mail()
  * @return bool True on completion. False if no email addresses were specified.
  */
 function wp_notify_postauthor( $comment_id, $deprecated = null ) {
@@ -1032,6 +1022,18 @@ function wp_notify_postauthor( $comment_id, $deprecated = null ) {
 
 	// Who to notify? By default, just the post author, but others can be added.
 	$emails = array( $author->user_email );
+
+	/**
+	 * Filter the list of emails to receive a comment notification.
+	 *
+	 * Normally just post authors are notified of emails.
+	 * This filter lets you add others.
+	 *
+	 * @since 3.7.0
+	 *
+	 * @param array $emails     Array of email addresses to receive a comment notification.
+	 * @param int   $comment_id The comment ID.
+	 */
 	$emails = apply_filters( 'comment_notification_recipients', $emails, $comment_id );
 	$emails = array_filter( $emails );
 
@@ -1043,7 +1045,17 @@ function wp_notify_postauthor( $comment_id, $deprecated = null ) {
 	// Facilitate unsetting below without knowing the keys.
 	$emails = array_flip( $emails );
 
-	// Post author may want to receive notifications for their own comments
+	/**
+	 * Filter whether to notify comment authors of their comments on their own posts.
+	 *
+	 * By default, comment authors don't get notified of their comments
+	 * on their own post. This lets you override that.
+	 *
+	 * @since 3.8.0
+	 *
+	 * @param bool $notify     Whether to notify the post author of their own comment. Default false.
+	 * @param int  $comment_id The comment ID.
+	 */
 	$notify_author = apply_filters( 'comment_notification_notify_author', false, $comment_id );
 
 	// The comment was left by the author