Ticket #25699: 25699.inline-docs.diff

src/wp-includes/comment.php

@@ -1378 +1378 @@
  *
  * @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 ) {

src/wp-includes/pluggable.php

@@ -1006 +1006 @@
  *
  * @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 +1022 @@
 
         // Who to notify? By default, just the post author, but others can be added.
         $emails = array( $author->user_email );
+
+        /**
+         * List of emails to be given a comment notification.
+         *
+         * Normally just post authors are notified of emails.
+         * This filter lets you add others.
+         *
+         * @since 3.7.0
+         *
+         * @param array $emails The emails to be notified of the comment.
+         * @param int $comment_id The comment ID.
+         */
         $emails = apply_filters( 'comment_notification_recipients', $emails, $comment_id );
         $emails = array_filter( $emails );
 
@@ -1043 +1045 @@
         // Facilitate unsetting below without knowing the keys.
         $emails = array_flip( $emails );
 
-        // Post author may want to receive notifications for their own comments
+        /**
+         * 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 Whether to notify the post author of their own comment.
+         * @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