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

src/bp-friends/bp-friends-template.php

@@ -26 +26 @@
          * @since BuddyPress (1.5.0)
          */
         function bp_get_friends_slug() {
+
+                /**
+                 * Filters the friends component slug.
+                 *
+                 * @since BuddyPress (1.5.0)
+                 *
+                 * @param string $value Friends component slug.
+                 */
                 return apply_filters( 'bp_get_friends_slug', buddypress()->friends->slug );
         }
 
@@ -45 +53 @@
          * @since BuddyPress (1.5.0)
          */
         function bp_get_friends_root_slug() {
+
+                /**
+                 * Filters the friends component root slug.
+                 *
+                 * @since BuddyPress (1.5.0)
+                 *
+                 * @param string $value Friends component root slug.
+                 */
                 return apply_filters( 'bp_get_friends_root_slug', buddypress()->friends->root_slug );
         }
 
@@ -212 +228 @@
         function bp_get_member_total_friend_count() {
                 global $members_template;
 
-                if ( 1 == (int) $members_template->member->total_friend_count )
+                if ( 1 == (int) $members_template->member->total_friend_count ) {
+
+                        /**
+                         * Filters text used to denote total friend count.
+                         *
+                         * @since BuddyPress (1.2.0)
+                         *
+                         * @param string $value String of the form "x friends".
+                         * @param int    $value Total friend count for current member in the loop.
+                         */
                         return apply_filters( 'bp_get_member_total_friend_count', sprintf( __( '%d friend', 'buddypress' ), (int) $members_template->member->total_friend_count ) );
-                else
+                } else {
+
+                        /** This filter is documented in bp-friends/bp-friends-template.php */
                         return apply_filters( 'bp_get_member_total_friend_count', sprintf( __( '%d friends', 'buddypress' ), (int) $members_template->member->total_friend_count ) );
+                }
         }
 
 /**
@@ -245 +273 @@
                 else if ( empty( $user_id ) && !isset( $friends_template->friendship->friend ) )
                         $user_id = bp_displayed_user_id();
 
+                /**
+                 * Filters the ID of current user in the friend request loop.
+                 *
+                 * @since BuddyPress (1.2.10)
+                 *
+                 * @param int $user_id ID of current user in the friend request loop.
+                 */
                 return apply_filters( 'bp_get_potential_friend_id', (int) $user_id );
         }
 
@@ -268 +303 @@
         if ( bp_loggedin_user_id() == $user_id )
                 return false;
 
+        /**
+         * Filters the status of friendship between logged in user and given user.
+         *
+         * @since BuddyPress (1.2.10)
+         *
+         * @param string $value String status of friendship. Possible values are
+         *                 'is_friend', 'not_friends', 'pending'.
+         */
         return apply_filters( 'bp_is_friend', friends_check_friendship_status( bp_loggedin_user_id(), $user_id ), $user_id );
 }
 
@@ -370 +413 @@
                                 break;
                 }
 
-                // Filter and return the HTML button
+                /**
+                 * Filters the HTML for the add friend button.
+                 *
+                 * @since BuddyPress (1.1.0)
+                 *
+                 * @param string $button HTML markup for add friend button.
+                 */
                 return bp_get_button( apply_filters( 'bp_get_add_friend_button', $button ) );
         }
 
@@ -422 +471 @@
                 $requests = 0;
         }
 
+        /**
+         * Filters the total pending friendship requests for a user.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param array|int An array of user IDs if found, or a 0 if none are found.
+         */
         return apply_filters( 'bp_get_friendship_requests', $requests );
 }
 
@@ -444 +500 @@
                         wp_cache_set( 'friendship_id_' . $members_template->member->id . '_' . bp_loggedin_user_id(), $friendship_id, 'bp' );
                 }
 
+                /**
+                 * Filters the ID of the friendship between the logged in user and the current user in the loop.
+                 *
+                 * @since BuddyPress (1.2.0)
+                 *
+                 * @param int $friendship_id ID of the friendship.
+                 */
                 return apply_filters( 'bp_get_friend_friendship_id', $friendship_id );
         }
 
@@ -466 +529 @@
                         wp_cache_set( 'friendship_id_' . $members_template->member->id . '_' . bp_loggedin_user_id(), $friendship_id, 'bp' );
                 }
 
+                /**
+                 * Filters the URL for accepting the current friendship request in the loop.
+                 *
+                 * @since BuddyPress (1.0.0)
+                 *
+                 * @param string $value Accept-friendship URL.
+                 */
                 return apply_filters( 'bp_get_friend_accept_request_link', wp_nonce_url( bp_loggedin_user_domain() . bp_get_friends_slug() . '/requests/accept/' . $friendship_id, 'friends_accept_friendship' ) );
         }
 
@@ -488 +558 @@
                         wp_cache_set( 'friendship_id_' . $members_template->member->id . '_' . bp_loggedin_user_id(), $friendship_id, 'bp' );
                 }
 
+                /**
+                 * Filters the URL for rejecting the current friendship request in the loop.
+                 *
+                 * @since BuddyPress (1.0.0)
+                 *
+                 * @param string $value Reject-friendship URL.
+                 */
                 return apply_filters( 'bp_get_friend_reject_request_link', wp_nonce_url( bp_loggedin_user_domain() . bp_get_friends_slug() . '/requests/reject/' . $friendship_id, 'friends_reject_friendship' ) );
         }
 
@@ -506 +583 @@
          * @return int Total friend count.
          */
         function bp_get_total_friend_count( $user_id = 0 ) {
+
+                /**
+                 * Filters the total friend count for a given user.
+                 *
+                 * @since BuddyPress (1.2.0)
+                 *
+                 * @param int $value Total friend count.
+                 */
                 return apply_filters( 'bp_get_total_friend_count', friends_get_total_friend_count( $user_id ) );
         }
         add_filter( 'bp_get_total_friend_count', 'bp_core_number_format' );
@@ -531 +616 @@
                 if ( empty( $user_id ) )
                         $user_id = bp_loggedin_user_id();
 
+                /**
+                 * Filters the total friendship request count for a given user.
+                 *
+                 * @since BuddyPress (1.2.0)
+                 *
+                 * @param int $value Friendship request count.
+                 */
                 return apply_filters( 'bp_friend_get_total_requests_count', count( BP_Friends_Friendship::get_friend_user_ids( $user_id, true ) ) );
         }
 
@@ -584 +676 @@
                 }
         }
 
-        // Filter and return
+        /**
+         * Filters the number of friends in user's profile.
+         *
+         * @since BuddyPress (2.0.0)
+         *
+         * @param string $value Formatted string displaying total friends count.
+         * @param array  $r Array of arguments for string formatting and output.
+         */
         return apply_filters( 'bp_friends_get_profile_stats', $r['output'], $r );
 }