Changeset 9174

Timestamp:

11/25/2014 02:51:59 PM (11 years ago)

Author:

boonebgorges

Message:

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

Props tw2113.
See #5942.

File:

• trunk/src/bp-friends/bp-friends-functions.php (modified) (14 diffs)

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

@@ -100 +100 @@
     $friendship    = new BP_Friends_Friendship( $friendship_id );
 
+    /**
+     * Fires before the deletion of a friendship activity item
+     * for the user who canceled the friendship.
+     *
+     * @since BuddyPress (1.5.0)
+     *
+     * @param int $friendship_id ID of the friendship object, if any, between a pair of users.
+     * @param int $initiator_userid ID of the friendship initiator.
+     * @param int $friend_userid ID of the friend user.
+     */
     do_action( 'friends_before_friendship_delete', $friendship_id, $initiator_userid, $friend_userid );
 
@@ -105 +115 @@
     friends_delete_activity( array( 'item_id' => $friendship_id, 'type' => 'friendship_accepted', 'user_id' => bp_displayed_user_id() ) );
 
-    // This hook is misleadingly named - the friendship is not yet deleted.
-    // This is your last chance to do something while the friendship exists
+    /**
+     * Fires before the friendship connection is removed.
+     *
+     * This hook is misleadingly named - the friendship is not yet deleted.
+     * This is your last chance to do something while the friendship exists.
+     *
+     * @since BuddyPress (1.0.0)
+     *
+     * @param int $friendship_id ID of the friendship object, if any, between a pair of users.
+     * @param int $initiator_userid ID of the friendship initiator.
+     * @param int $friend_userid ID of the friend user.
+     */
     do_action( 'friends_friendship_deleted', $friendship_id, $initiator_userid, $friend_userid );
 
@@ -112 +132 @@
         friends_update_friend_totals( $initiator_userid, $friend_userid, 'remove' );
 
+        /**
+         * Fires after the friendship connection is removed.
+         *
+         * @since BuddyPress (1.8.0)
+         *
+         * @param int $initiator_userid ID of the friendship initiator.
+         * @param int $friend_userid ID of the friend user.
+         */
         do_action( 'friends_friendship_post_delete', $initiator_userid, $friend_userid );
 
@@ -139 +167 @@
         friends_update_friend_totals( $friendship->initiator_user_id, $friendship->friend_user_id );
 
+        /**
+         * Fires after a friendship is accepted.
+         *
+         * @since BuddyPress (1.0.0)
+         *
+         * @param int    $id ID of the pending friendship object.
+         * @param int    $initiator_user_id ID of the friendship initiator.
+         * @param int    $friend_user_id ID of the user requested friendship with.
+         * @param object $friendship BuddyPress Friendship Object.
+         */
         do_action( 'friends_friendship_accepted', $friendship->id, $friendship->initiator_user_id, $friendship->friend_user_id, $friendship );
 
@@ -157 +195 @@
 
     if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::reject( $friendship_id ) ) {
+
+        /**
+         * Fires after a friendship request is rejected.
+         *
+         * @since BuddyPress (1.0.0)
+         *
+         * @param int                   $friendship_id ID of the pending friendship.
+         * @param BP_Friends_Friendship $friendships Friendship object. Passed by reference.
+         */
         do_action_ref_array( 'friends_friendship_rejected', array( $friendship_id, &$friendship ) );
         return true;
@@ -181 +228 @@
         do_action_ref_array( 'friends_friendship_whithdrawn', array( $friendship_id, &$friendship ) );
 
-        // @since 1.9
+        /**
+         * Fires after a friendship request has been withdrawn.
+         *
+         * @since BuddyPress (1.9.0)
+         *
+         * @param int                   $friendship_id ID of the friendship.
+         * @param BP_Friends_Friendship $friendship Friendship object. Passed by reference.
+         */
         do_action_ref_array( 'friends_friendship_withdrawn',  array( $friendship_id, &$friendship ) );
 
@@ -247 +301 @@
         $count = 0;
 
+    /**
+     * Filters the total friend count for a given user.
+     *
+     * @since BuddyPress (1.2.0)
+     *
+     * @param int $count Total friend count for a given user.
+     */
     return apply_filters( 'friends_get_total_friend_count', $count );
 }
@@ -338 +399 @@
  */
 function friends_get_recently_active( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
+
+    /**
+     * Filters a user's most recently active friends.
+     *
+     * @since BuddyPress (1.2.0)
+     *
+     * @param array {
+     *     @type int   $total_users Total number of users matched by query params.
+     *     @type array $paged_users The current page of users matched by query params.
+     * }
+     */
     return apply_filters( 'friends_get_recently_active', BP_Core_User::get_users( 'active', $per_page, $page, $user_id, $filter ) );
 }
@@ -356 +428 @@
  */
 function friends_get_alphabetically( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
+
+    /**
+     * Filters a user's friends listed in alphabetical order.
+     *
+     * @since BuddyPress (1.2.0)
+     *
+     * @return array {
+     *     @type int   $total_users Total number of users matched by query params.
+     *     @type array $paged_users The current page of users matched by query params.
+     * }
+     */
     return apply_filters( 'friends_get_alphabetically', BP_Core_User::get_users( 'alphabetical', $per_page, $page, $user_id, $filter ) );
 }
@@ -374 +457 @@
  */
 function friends_get_newest( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
+
+    /**
+     * Filters a user's friends listed from newest to oldest.
+     *
+     * @since BuddyPress (1.2.0)
+     *
+     * @param array {
+     *     @type int   $total_users Total number of users matched by query params.
+     *     @type array $paged_users The current page of users matched by query params.
+     * }
+     */
     return apply_filters( 'friends_get_newest', BP_Core_User::get_users( 'newest', $per_page, $page, $user_id, $filter ) );
 }
@@ -415 +509 @@
     $friends = array();
 
-    // Default args
+    /**
+     * Filters default arguments for list of friends a user can invite into this group.
+     *
+     * @since BuddyPress (1.5.4)
+     *
+     * @param array $value Array of default paremters for invite list.
+     */
     $args = apply_filters( 'bp_friends_pre_get_invite_list', array(
         'user_id'  => $user_id,
@@ -462 +562 @@
         $friends = false;
 
-    // Allow friends to be filtered
+    /**
+     * Filters the list of potential friends that can be invited to this group.
+     *
+     * @since BuddyPress (1.5.4)
+     *
+     * @param array|bool $friends Array friends available to invite or false for no friends.
+     * @param int        $user_id ID of the user checked for who they can invite.
+     * @param int        $group_id ID of the group being checked on.
+     */
     return apply_filters( 'bp_friends_get_invite_list', $friends, $user_id, $group_id );
 }
@@ -567 +675 @@
 function friends_remove_data( $user_id ) {
 
+    /**
+     * Fires before deletion of friend-related data for a given user.
+     *
+     * @since BuddyPress (1.5.0)
+     *
+     * @param int $user_id ID for the user whose friend data is being removed.
+     */
     do_action( 'friends_before_remove_data', $user_id );
 
@@ -574 +689 @@
     bp_delete_user_meta( $user_id, 'total_friend_count' );
 
+    /**
+     * Fires after deletion of friend-related data for a given user.
+     *
+     * @since BuddyPress (1.0.0)
+     *
+     * @param int $user_id ID for the user whose friend data is being removed.
+     */
     do_action( 'friends_remove_data', $user_id );
 }