Changeset 9175

Timestamp:

11/25/2014 03:00:37 PM (11 years ago)

Author:

boonebgorges

Message:

Add hook documentation in bp-friends-notifications.php.

Props tw2113.
See #5942.

File:

• trunk/src/bp-friends/bp-friends-notifications.php (modified) (4 diffs)

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

@@ -57 +57 @@
     }
 
-    // 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 );
 }
@@ -106 +144 @@
     }
 
-    // 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 );
 }
@@ -170 +245 @@
     // 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,
@@ -178 +273 @@
     }
 
+    /**
+     * 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 );