Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
07/04/2015 10:23:19 PM (5 years ago)
Author:
tw2113
Message:

Docs cleanup for Friends component.

See #6400.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/bp-friends/bp-friends-functions.php

    r9819 r9995  
    22
    33/**
    4  * BuddyPress Friends Functions
     4 * BuddyPress Friends Functions.
    55 *
    66 * Functions are where all the magic happens in BuddyPress. They will
     
    1919 * Create a new friendship.
    2020 *
    21  * @param int $initiator_userid ID of the "initiator" user (the user who is
    22  *        sending the friendship request).
    23  * @param int $friend_userid ID of the "friend" user (the user whose friendship
    24  *        is being requested).
    25  * @param bool $force_accept Optional. Whether to force acceptance. When false,
    26  *        running friends_add_friend() will result in a friendship request.
    27  *        When true, running friends_add_friend() will result in an accepted
    28  *        friendship, with no notifications being sent. Default: false.
     21 * @param int  $initiator_userid ID of the "initiator" user (the user who is
     22 *                               sending the friendship request).
     23 * @param int  $friend_userid    ID of the "friend" user (the user whose friendship
     24 *                               is being requested).
     25 * @param bool $force_accept     Optional. Whether to force acceptance. When false,
     26 *                               running friends_add_friend() will result in a friendship request.
     27 *                               When true, running friends_add_friend() will result in an accepted
     28 *                               friendship, with no notifications being sent. Default: false.
     29 *
    2930 * @return bool True on success, false on failure.
    3031 */
     
    7677     * @since BuddyPress (1.0.0)
    7778     *
    78      * @param int    $id ID of the pending friendship connection.
     79     * @param int    $id                ID of the pending friendship connection.
    7980     * @param int    $initiator_user_id ID of the friendship initiator.
    80      * @param int    $friend_user_id ID of the friend user.
    81      * @param object $friendship BuddyPress Friendship Object.
     81     * @param int    $friend_user_id    ID of the friend user.
     82     * @param object $friendship        BuddyPress Friendship Object.
    8283     */
    8384    do_action( 'friends_friendship_' . $action, $friendship->id, $friendship->initiator_user_id, $friendship->friend_user_id, $friendship );
     
    9293 *
    9394 * @param int $initiator_userid ID of the friendship initiator.
    94  * @param int $friend_userid ID of the friend user.
     95 * @param int $friend_userid    ID of the friend user.
     96 *
    9597 * @return bool True on success, false on failure.
    9698 */
     
    106108     * @since BuddyPress (1.5.0)
    107109     *
    108      * @param int $friendship_id ID of the friendship object, if any, between a pair of users.
     110     * @param int $friendship_id    ID of the friendship object, if any, between a pair of users.
    109111     * @param int $initiator_userid ID of the friendship initiator.
    110      * @param int $friend_userid ID of the friend user.
     112     * @param int $friend_userid    ID of the friend user.
    111113     */
    112114    do_action( 'friends_before_friendship_delete', $friendship_id, $initiator_userid, $friend_userid );
     
    123125     * @since BuddyPress (1.0.0)
    124126     *
    125      * @param int $friendship_id ID of the friendship object, if any, between a pair of users.
     127     * @param int $friendship_id    ID of the friendship object, if any, between a pair of users.
    126128     * @param int $initiator_userid ID of the friendship initiator.
    127      * @param int $friend_userid ID of the friend user.
     129     * @param int $friend_userid    ID of the friend user.
    128130     */
    129131    do_action( 'friends_friendship_deleted', $friendship_id, $initiator_userid, $friend_userid );
     
    138140         *
    139141         * @param int $initiator_userid ID of the friendship initiator.
    140          * @param int $friend_userid ID of the friend user.
     142         * @param int $friend_userid    ID of the friend user.
    141143         */
    142144        do_action( 'friends_friendship_post_delete', $initiator_userid, $friend_userid );
     
    154156 *
    155157 * @param int $friendship_id ID of the pending friendship object.
     158 *
    156159 * @return bool True on success, false on failure.
    157160 */
     
    172175         * @since BuddyPress (1.0.0)
    173176         *
    174          * @param int    $id ID of the pending friendship object.
     177         * @param int    $id                ID of the pending friendship object.
    175178         * @param int    $initiator_user_id ID of the friendship initiator.
    176          * @param int    $friend_user_id ID of the user requested friendship with.
    177          * @param object $friendship BuddyPress Friendship Object.
     179         * @param int    $friend_user_id    ID of the user requested friendship with.
     180         * @param object $friendship        BuddyPress Friendship Object.
    178181         */
    179182        do_action( 'friends_friendship_accepted', $friendship->id, $friendship->initiator_user_id, $friendship->friend_user_id, $friendship );
     
    189192 *
    190193 * @param int $friendship_id ID of the pending friendship object.
     194 *
    191195 * @return bool True on success, false on failure.
    192196 */
     
    215219 *
    216220 * @param int $initiator_userid ID of the friendship initiator - this is the
    217  *            user who requested the friendship, and is doing the withdrawing.
    218  * @param int $friend_userid ID of the requested friend.
     221 *                              user who requested the friendship, and is doing the withdrawing.
     222 * @param int $friend_userid    ID of the requested friend.
     223 *
    219224 * @return bool True on success, false on failure.
    220225 */
     
    234239         *
    235240         * @param int                   $friendship_id ID of the friendship.
    236          * @param BP_Friends_Friendship $friendship Friendship object. Passed by reference.
     241         * @param BP_Friends_Friendship $friendship    Friendship object. Passed by reference.
    237242         */
    238243        do_action_ref_array( 'friends_friendship_withdrawn',  array( $friendship_id, &$friendship ) );
     
    247252 * Check whether two users are friends.
    248253 *
    249  * @param int $user_id ID of the first user.
     254 * @param int $user_id            ID of the first user.
    250255 * @param int $possible_friend_id ID of the other user.
     256 *
    251257 * @return bool Returns true if the two users are friends, otherwise false.
    252258 */
     
    264270 * Will return 'is_friends', 'not_friends', 'pending' or 'awaiting_response'.
    265271 *
    266  * @param int $user_id ID of the first user.
     272 * @param int $user_id            ID of the first user.
    267273 * @param int $possible_friend_id ID of the other user.
     274 *
    268275 * @return string Friend status of the two users.
    269276 */
     
    291298 *
    292299 * @param int $user_id ID of the user whose friends are being counted.
     300 *
    293301 * @return int Friend count of the user.
    294302 */
     
    315323 *
    316324 * @param int $user_id ID of the user whose friends are being checked.
     325 *
    317326 * @return bool True if the user has friends, otherwise false.
    318327 */
     
    333342 *
    334343 * @param int $initiator_user_id ID of the first user.
    335  * @param int $friend_user_id ID of the second user.
     344 * @param int $friend_user_id    ID of the second user.
     345 *
    336346 * @return int|bool ID of the friendship if found, otherwise false.
    337347 */
     
    343353 * Get the IDs of a given user's friends.
    344354 *
    345  * @param int $user_id ID of the user whose friends are being retrieved.
     355 * @param int  $user_id              ID of the user whose friends are being retrieved.
    346356 * @param bool $friend_requests_only Optional. Whether to fetch unaccepted
    347  *        requests only. Default: false.
    348  * @param bool $assoc_arr Optional. True to receive an array of arrays keyed as
    349  *        'user_id' => $user_id; false to get a one-dimensional array of user
    350  *        IDs. Default: false.
     357 *                                   requests only. Default: false.
     358 * @param bool $assoc_arr            Optional. True to receive an array of arrays keyed as
     359 *                                   'user_id' => $user_id; false to get a one-dimensional
     360 *                                   array of user IDs. Default: false.
     361 *
     362 * @return array
    351363 */
    352364function friends_get_friend_user_ids( $user_id, $friend_requests_only = false, $assoc_arr = false ) {
     
    357369 * Search the friends of a user by a search string.
    358370 *
    359  * @param string $filter The search string, matched against xprofile fields (if
    360  *        available), or usermeta 'nickname' field.
    361  * @param int $user_id ID of the user whose friends are being searched.
    362  * @param int $limit Optional. Max number of friends to return.
    363  * @param int $page Optional. The page of results to return. Default: null (no
    364  *        pagination - return all results).
     371 * @param string $search_terms The search string, matched against xprofile fields (if
     372 *                             available), or usermeta 'nickname' field.
     373 * @param int    $user_id      ID of the user whose friends are being searched.
     374 * @param int    $pag_num      Optional. Max number of friends to return.
     375 * @param int    $pag_page     Optional. The page of results to return. Default: null (no
     376 *                             pagination - return all results).
     377 *
    365378 * @return array|bool On success, an array: {
    366379 *     @type array $friends IDs of friends returned by the query.
    367  *     @type int $count Total number of friends (disregarding
    368  *           pagination) who match the search.
     380 *     @type int   $count  Total number of friends (disregarding
     381 *                          pagination) who match the search.
    369382 * }. Returns false on failure.
    370383 */
     
    376389 * Get a list of IDs of users who have requested friendship of a given user.
    377390 *
    378  * @param int $user_id The ID of the user who has received the friendship
    379  *        requests.
     391 * @param int $user_id The ID of the user who has received the friendship requests.
     392 *
    380393 * @return array|bool An array of user IDs, or false if none are found.
    381394 */
     
    389402 * @see BP_Core_User::get_users() for a description of return value.
    390403 *
    391  * @param int $user_id ID of the user whose friends are being retrieved.
    392  * @param int $per_page Optional. Number of results to return per page.
    393  *        Default: 0 (no pagination; show all results).
    394  * @param int $page Optional. Number of the page of results to return.
    395  *        Default: 0 (no pagination; show all results).
    396  * @param string $filter Optional. Limit results to those matching a search
    397  *        string.
     404 * @param int    $user_id  ID of the user whose friends are being retrieved.
     405 * @param int    $per_page Optional. Number of results to return per page.
     406 *                         Default: 0 (no pagination; show all results).
     407 * @param int    $page     Optional. Number of the page of results to return.
     408 *                         Default: 0 (no pagination; show all results).
     409 * @param string $filter   Optional. Limit results to those matching a search
     410 *                         string.
     411 *
    398412 * @return array See {@link BP_Core_User::get_users()}.
    399413 */
     
    418432 * @see BP_Core_User::get_users() for a description of return value.
    419433 *
    420  * @param int $user_id ID of the user whose friends are being retrieved.
    421  * @param int $per_page Optional. Number of results to return per page.
    422  *        Default: 0 (no pagination; show all results).
    423  * @param int $page Optional. Number of the page of results to return.
    424  *        Default: 0 (no pagination; show all results).
    425  * @param string $filter Optional. Limit results to those matching a search
    426  *        string.
     434 * @param int    $user_id  ID of the user whose friends are being retrieved.
     435 * @param int    $per_page Optional. Number of results to return per page.
     436 *                         Default: 0 (no pagination; show all results).
     437 * @param int    $page     Optional. Number of the page of results to return.
     438 *                         Default: 0 (no pagination; show all results).
     439 * @param string $filter   Optional. Limit results to those matching a search
     440 *                         string.
     441 *
    427442 * @return array See {@link BP_Core_User::get_users()}.
    428443 */
     
    447462 * @see BP_Core_User::get_users() for a description of return value.
    448463 *
    449  * @param int $user_id ID of the user whose friends are being retrieved.
    450  * @param int $per_page Optional. Number of results to return per page.
    451  *        Default: 0 (no pagination; show all results).
    452  * @param int $page Optional. Number of the page of results to return.
    453  *        Default: 0 (no pagination; show all results).
    454  * @param string $filter Optional. Limit results to those matching a search
    455  *        string.
     464 * @param int    $user_id  ID of the user whose friends are being retrieved.
     465 * @param int    $per_page Optional. Number of results to return per page.
     466 *                         Default: 0 (no pagination; show all results).
     467 * @param int    $page     Optional. Number of the page of results to return.
     468 *                         Default: 0 (no pagination; show all results).
     469 * @param string $filter   Optional. Limit results to those matching a search
     470 *                         string.
     471 *
    456472 * @return array See {@link BP_Core_User::get_users()}.
    457473 */
     
    477493 *      arguments and return value.
    478494 *
    479  * @param array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
     495 * @param array $friend_ids See BP_Friends_Friendship::get_bulk_last_active().
     496 *
    480497 * @return array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
    481498 */
     
    492509 * @since BuddyPress (1.0.0)
    493510 *
    494  * @param int $user_id User ID whose friends to see can be invited. Default:
    495  *        ID of the logged-in user.
     511 * @param int $user_id  User ID whose friends to see can be invited. Default:
     512 *                      ID of the logged-in user.
    496513 * @param int $group_id Group to check possible invitations against.
     514 *
    497515 * @return mixed False if no friends, array of users if friends.
    498516 */
     
    567585     * @since BuddyPress (1.5.4)
    568586     *
    569      * @param array|bool $friends Array friends available to invite or false for no friends.
    570      * @param int        $user_id ID of the user checked for who they can invite.
     587     * @param array|bool $friends  Array friends available to invite or false for no friends.
     588     * @param int        $user_id  ID of the user checked for who they can invite.
    571589     * @param int        $group_id ID of the group being checked on.
    572590     */
     
    583601 * - users who have been banned from the group
    584602 *
    585  * @param int $user_id ID of the user whose friends are being counted.
     603 * @param int $user_id  ID of the user whose friends are being counted.
    586604 * @param int $group_id ID of the group friends are being invited to.
     605 *
    587606 * @return int $invitable_count Eligible friend count.
    588607 */
     
    595614 *
    596615 * @param int $user_id Optional. ID of the user whose friendships you are
    597  *        counting. Default: displayed user (if any), otherwise logged-in user.
     616 *                     counting. Default: displayed user (if any), otherwise logged-in user.
     617 *
    598618 * @return int Friend count for the user.
    599619 */
     
    606626 *
    607627 * @param string $search_terms Search term to filter on.
    608  * @param int $user_id ID of the user whose friends are being searched.
    609  * @param int $pag_num Number of results to return per page. Default: 0 (no
    610  *        pagination - show all results).
    611  * @param int $pag_num Number of the page being requested. Default: 0 (no
    612  *        pagination - show all results).
     628 * @param int    $user_id      ID of the user whose friends are being searched.
     629 * @param int    $pag_num      Number of results to return per page. Default: 0 (no
     630 *                             pagination - show all results).
     631 * @param int    $pag_page     Number of the page being requested. Default: 0 (no
     632 *                             pagination - show all results).
     633 *
    613634 * @return array Array of BP_Core_User objects corresponding to friends.
    614635 */
     
    631652 *
    632653 * @param int $friendship_id The ID of the friendship being checked.
     654 *
    633655 * @return bool True if the friendship is confirmed, otherwise false.
    634656 */
     
    645667 * the cached values.
    646668 *
    647  * @param int $initiator_user_id ID of the first user.
    648  * @param int $friend_user_id ID of the second user.
    649  * @param string $status Optional. The friendship event that's been triggered.
    650  *        'add' will ++ each user's friend counts, while any other string
    651  *        will --.
     669 * @param int    $initiator_user_id ID of the first user.
     670 * @param int    $friend_user_id    ID of the second user.
     671 * @param string $status            Optional. The friendship event that's been triggered.
     672 *                                  'add' will ++ each user's friend counts, while any other string
     673 *                                  will --.
    652674 */
    653675function friends_update_friend_totals( $initiator_user_id, $friend_user_id, $status = 'add' ) {
     
    667689 * Removes the following:
    668690 *
    669  * - Friendships of which the user is a member
    670  * - Cached friend count for the user
    671  * - Notifications of friendship requests sent by the user
     691 * - Friendships of which the user is a member.
     692 * - Cached friend count for the user.
     693 * - Notifications of friendship requests sent by the user.
    672694 *
    673695 * @param int $user_id ID of the user whose friend data is being removed.
Note: See TracChangeset for help on using the changeset viewer.