Changeset 10323 for trunk/src/bp-friends/bp-friends-functions.php

Timestamp:

11/02/2015 02:07:44 AM (9 years ago)

Author:

tw2113

Message:

More docs cleanup for Friends component.

See #6400.

File:

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

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

@@ -26 +26 @@
  *                               When true, running friends_add_friend() will result in an accepted
  *                               friendship, with no notifications being sent. Default: false.
- *
  * @return bool True on success, false on failure.
  */
@@ -36 +35 @@
     }
 
-    // Check if already friends, and bail if so
+    // Check if already friends, and bail if so.
     if ( friends_check_friendship( $initiator_userid, $friend_userid ) ) {
         return true;
     }
 
-    // Setup the friendship data
+    // Setup the friendship data.
     $friendship = new BP_Friends_Friendship;
     $friendship->initiator_user_id = $initiator_userid;
@@ -53 +52 @@
     }
 
-    // Bail if friendship could not be saved (how sad!)
+    // Bail if friendship could not be saved (how sad!).
     if ( ! $friendship->save() ) {
         return false;
     }
 
-    // Send notifications
+    // Send notifications.
     if ( empty( $force_accept ) ) {
         $action = 'requested';
 
-    // Update friend totals
+    // Update friend totals.
     } else {
         $action = 'accepted';
@@ -93 +92 @@
  * @param int $initiator_userid ID of the friendship initiator.
  * @param int $friend_userid    ID of the friend user.
- *
  * @return bool True on success, false on failure.
  */
@@ -113 +111 @@
     do_action( 'friends_before_friendship_delete', $friendship_id, $initiator_userid, $friend_userid );
 
-    // Remove the activity stream items about the friendship id
+    // Remove the activity stream items about the friendship id.
     friends_delete_activity( array( 'item_id' => $friendship_id, 'type' => 'friendship_created', 'user_id' => 0 ) );
 
@@ -155 +153 @@
  *
  * @param int $friendship_id ID of the pending friendship object.
- *
  * @return bool True on success, false on failure.
  */
 function friends_accept_friendship( $friendship_id ) {
 
-    // Get the friendship data
+    // Get the friendship data.
     $friendship = new BP_Friends_Friendship( $friendship_id, true, false );
 
-    // Accepting friendship
+    // Accepting friendship.
     if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::accept( $friendship_id ) ) {
 
-        // Bump the friendship counts
+        // Bump the friendship counts.
         friends_update_friend_totals( $friendship->initiator_user_id, $friendship->friend_user_id );
 
@@ -191 +188 @@
  *
  * @param int $friendship_id ID of the pending friendship object.
- *
  * @return bool True on success, false on failure.
  */
@@ -220 +216 @@
  *                              user who requested the friendship, and is doing the withdrawing.
  * @param int $friend_userid    ID of the requested friend.
- *
  * @return bool True on success, false on failure.
  */
@@ -253 +248 @@
  * @param int $user_id            ID of the first user.
  * @param int $possible_friend_id ID of the other user.
- *
  * @return bool Returns true if the two users are friends, otherwise false.
  */
@@ -271 +265 @@
  * @param int $user_id            ID of the first user.
  * @param int $possible_friend_id ID of the other user.
- *
  * @return string Friend status of the two users.
  */
@@ -277 +270 @@
     global $members_template;
 
-    // check the BP_User_Query first
-    // @see bp_friends_filter_user_query_populate_extras()
+    // Check the BP_User_Query first
+    // @see bp_friends_filter_user_query_populate_extras().
     if ( ! empty( $members_template->in_the_loop ) ) {
         if ( isset( $members_template->member->friendship_status ) ) {
@@ -292 +285 @@
  *
  * @param int $user_id ID of the user whose friends are being counted.
- *
  * @return int Friend count of the user.
  */
@@ -317 +309 @@
  *
  * @param int $user_id ID of the user whose friends are being checked.
- *
  * @return bool True if the user has friends, otherwise false.
  */
@@ -337 +328 @@
  * @param int $initiator_user_id ID of the first user.
  * @param int $friend_user_id    ID of the second user.
- *
  * @return int|bool ID of the friendship if found, otherwise false.
  */
@@ -353 +343 @@
  *                                   'user_id' => $user_id; false to get a one-dimensional
  *                                   array of user IDs. Default: false.
- *
  * @return array
  */
@@ -369 +358 @@
  * @param int    $pag_page     Optional. The page of results to return. Default: null (no
  *                             pagination - return all results).
- *
  * @return array|bool On success, an array: {
  *     @type array $friends IDs of friends returned by the query.
@@ -384 +372 @@
  *
  * @param int $user_id The ID of the user who has received the friendship requests.
- *
  * @return array|bool An array of user IDs, or false if none are found.
  */
@@ -403 +390 @@
  * @param string $filter   Optional. Limit results to those matching a search
  *                         string.
- *
  * @return array See {@link BP_Core_User::get_users()}.
  */
@@ -433 +419 @@
  * @param string $filter   Optional. Limit results to those matching a search
  *                         string.
- *
  * @return array See {@link BP_Core_User::get_users()}.
  */
@@ -463 +448 @@
  * @param string $filter   Optional. Limit results to those matching a search
  *                         string.
- *
  * @return array See {@link BP_Core_User::get_users()}.
  */
@@ -488 +472 @@
  *
  * @param array $friend_ids See BP_Friends_Friendship::get_bulk_last_active().
- *
  * @return array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
  */
@@ -506 +489 @@
  *                      ID of the logged-in user.
  * @param int $group_id Group to check possible invitations against.
- *
  * @return mixed False if no friends, array of users if friends.
  */
 function friends_get_friends_invite_list( $user_id = 0, $group_id = 0 ) {
 
-    // Default to logged in user id
+    // Default to logged in user id.
     if ( empty( $user_id ) )
         $user_id = bp_loggedin_user_id();
 
-    // Only group admins can invited previously banned users
+    // Only group admins can invited previously banned users.
     $user_is_admin = (bool) groups_is_user_admin( $user_id, $group_id );
 
-    // Assume no friends
+    // Assume no friends.
     $friends = array();
 
@@ -534 +516 @@
     ) );
 
-    // User has friends
+    // User has friends.
     if ( bp_has_members( $args ) ) {
 
@@ -547 +529 @@
         while ( bp_members() ) :
 
-            // Load the member
+            // Load the member.
             bp_the_member();
 
-            // Get the user ID of the friend
+            // Get the user ID of the friend.
             $friend_user_id = bp_get_member_user_id();
 
-            // Skip friend if already in the group
+            // Skip friend if already in the group.
             if ( groups_is_user_member( $friend_user_id, $group_id ) )
                 continue;
 
-            // Skip friend if not group admin and user banned from group
+            // Skip friend if not group admin and user banned from group.
             if ( ( false === $user_is_admin ) && groups_is_user_banned( $friend_user_id, $group_id ) )
                 continue;
 
-            // Friend is safe, so add it to the array of possible friends
+            // Friend is safe, so add it to the array of possible friends.
             $friends[] = array(
                 'id'        => $friend_user_id,
@@ -570 +552 @@
     }
 
-    // If no friends, explicitly set to false
+    // If no friends, explicitly set to false.
     if ( empty( $friends ) )
         $friends = false;
@@ -597 +579 @@
  * @param int $user_id  ID of the user whose friends are being counted.
  * @param int $group_id ID of the group friends are being invited to.
- *
  * @return int $invitable_count Eligible friend count.
  */
@@ -609 +590 @@
  * @param int $user_id Optional. ID of the user whose friendships you are
  *                     counting. Default: displayed user (if any), otherwise logged-in user.
- *
  * @return int Friend count for the user.
  */
@@ -625 +605 @@
  * @param int    $pag_page     Number of the page being requested. Default: 0 (no
  *                             pagination - show all results).
- *
  * @return array Array of BP_Core_User objects corresponding to friends.
  */
@@ -646 +625 @@
  *
  * @param int $friendship_id The ID of the friendship being checked.
- *
  * @return bool True if the friendship is confirmed, otherwise false.
  */
@@ -702 +680 @@
     BP_Friends_Friendship::delete_all_for_user( $user_id );
 
-    // Remove usermeta
+    // Remove usermeta.
     bp_delete_user_meta( $user_id, 'total_friend_count' );
 
@@ -740 +718 @@
 
     $friends_query = array(
-        'count_total'     => '',                    // Prevents total count
+        'count_total'     => '',                    // Prevents total count.
         'populate_extras' => false,