Ticket #5942: bp-friends-notifications-5942.diff

src/bp-friends/bp-friends-notifications.php

@@ -56 +56 @@
                 $message .= sprintf( __( 'To disable these notifications please log in and go to: %s', 'buddypress' ), $settings_link );
         }
 
-        // Send the message
+        /**
+         * Filters the email address for who is getting the friend request.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $to Email address for who is getting the friend request.
+         */
         $to      = apply_filters( 'friends_notification_new_request_to', $to );
+
+        /**
+         * Filters the subject for the friend request email.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $subject Subject line to be used in friend request email.
+         * @param string $initiator_name Name of the person requesting friendship.
+         */
         $subject = apply_filters( 'friends_notification_new_request_subject', $subject, $initiator_name );
+
+        /**
+         * Filters the message for the friend request email.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $message Message to be used in friend request email.
+         * @param string $initiator_name Name of the person requesting friendship.
+         * @param string $initiator_link Profile link of person requesting friendship.
+         * @param string $all_requests_link User's friends request management link.
+         * @param string $settings_link Email recipient's settings management link.
+         */
         $message = apply_filters( 'friends_notification_new_request_message', $message, $initiator_name, $initiator_link, $all_requests_link, $settings_link );
 
         wp_mail( $to, $subject, $message );
 
+        /**
+         * Fires after the new friend request email is sent.
+         *
+         * @since BuddyPress (1.5.0)
+         *
+         * @param int    $friend_id ID of the request recipient.
+         * @param string $subject Text for the friend request subject field.
+         * @param string $message Text for the friend request message field.
+         * @param int    $friendship_id ID of the friendship object.
+         * @param int    $initiator_id ID of the friendship requester.
+         */
         do_action( 'bp_friends_sent_request_email', $friend_id, $subject, $message, $friendship_id, $initiator_id );
 }
 add_action( 'friends_friendship_requested', 'friends_notification_new_request', 10, 3 );
@@ -105 +143 @@
                 $message .= sprintf( __( 'To disable these notifications please log in and go to: %s', 'buddypress' ), $settings_link );
         }
 
-        // Send the message
+        /**
+         * Filters the email address for whose friend request got accepted.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $to Email address for whose friend request got accepted.
+         */
         $to      = apply_filters( 'friends_notification_accepted_request_to', $to );
+
+        /**
+         * Filters the subject for the friend request accepted email.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $subject Subject line to be used in friend
+         *                 request accepted email.
+         * @param string $friend_name Name of the person who accepted
+         *                 the friendship request.
+         */
         $subject = apply_filters( 'friends_notification_accepted_request_subject', $subject, $friend_name );
+
+        /**
+         * Filters the message for the friend request accepted email.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $message Message to be used in friend request email.
+         * @param string $friend_name Name of the person who accepted
+         *                 the friendship request.
+         * @param string $friend_link Profile link of person who accepted
+         *                 the friendship request.
+         * @param string $settings_link Email recipient's settings management link.
+         */
         $message = apply_filters( 'friends_notification_accepted_request_message', $message, $friend_name, $friend_link, $settings_link );
 
         wp_mail( $to, $subject, $message );
 
+        /**
+         * Fires after the friend request accepted email is sent.
+         *
+         * @since BuddyPress (1.5.0)
+         *
+         * @param int    $initiator_id ID of the friendship requester.
+         * @param string $subject Text for the friend request subject field.
+         * @param string $message Text for the friend request message field.
+         * @param int    $friendship_id ID of the friendship object.
+         * @param int    $friend_id ID of the request recipient.
+         */
         do_action( 'bp_friends_sent_accepted_email', $initiator_id, $subject, $message, $friendship_id, $friend_id );
 }
 add_action( 'friends_friendship_accepted', 'friends_notification_accepted_request', 10, 3 );
@@ -136 +215 @@
                 case 'friendship_accepted':
                         $link = trailingslashit( bp_loggedin_user_domain() . bp_get_friends_slug() . '/my-friends' );
 
-                        // $action and $amount are used to generate dynamic filter names.
                         $action = 'accepted';
 
                         // Set up the string and the filter
@@ -169 +247 @@
 
         // Return either an HTML link or an array, depending on the requested format
         if ( 'string' == $format ) {
+
+                /**
+                 * Filters the format of friendship notifications based on type and amount
+                 * of notifications pending.
+                 *
+                 * This is a variable filter that has four possible versions.
+                 * The four possible versions are:
+                 *              bp_friends_single_friendship_accepted_notification
+                 *              bp_friends_multiple_friendship_accepted_notification
+                 *              bp_friends_single_friendship_request_notification
+                 *              bp_friends_multiple_friendship_request_notification
+                 *
+                 * @since BuddyPress (1.0.0)
+                 *
+                 * @param string|array $value Depending on format, an HTML link to new
+                 *                       requests profile tab or array with link and text.
+                 * @param int          $total_items The total number of messaging-related
+                 *                       notifications waiting for the user.
+                 * @param int          $item_id The primary item ID.
+                 */
                 $return = apply_filters( 'bp_friends_' . $amount . '_friendship_' . $action . '_notification', '<a href="' . esc_url( $link ) . '">' . esc_html( $text ) . '</a>', (int) $total_items, $item_id );
         } else {
+                /** This filter is documented in bp-friends/bp-friends-notifications.php */
                 $return = apply_filters( 'bp_friends_' . $amount . '_friendship_' . $action . '_notification', array(
                         'link' => $link,
                         'text' => $text
@@ -177 +276 @@
                 ), (int) $total_items, $item_id );
         }
 
+        /**
+         * Fires at the end of the bp-friends notification format callback.
+         *
+         * @since BuddyPress (1.0.0)
+         *
+         * @param string       $action The kind of notification being rendered.
+         * @param int          $item_id The primary item ID.
+         * @param int          $secondary_item_id The secondary item ID.
+         * @param int          $total_items The total number of messaging-related notifications
+         *                       waiting for the user.
+         * @param array|string $return Notification text string or array of link and text.
+         */
         do_action( 'friends_format_notifications', $action, $item_id, $secondary_item_id, $total_items, $return );
 
         return $return;