Skip to:
Content

BuddyPress.org

Changeset 9995


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

Docs cleanup for Friends component.

See #6400.

Location:
trunk/src/bp-friends
Files:
12 edited

Legend:

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

    r9819 r9995  
    22
    33/**
    4  * BuddyPress Friends Actions
     4 * BuddyPress Friends Actions.
    55 *
    66 * Action functions are exactly the same as screen functions, however they do
  • trunk/src/bp-friends/bp-friends-activity.php

    r9819 r9995  
    22
    33/**
    4  * BuddyPress Friends Activity Functions
     4 * BuddyPress Friends Activity Functions.
    55 *
    66 * These functions handle the recording, deleting and formatting of activity
     
    2323 *      return values.
    2424 *
    25  * @param array $args {
     25 * @param array|string $args {
    2626 *     An array of arguments for the new activity item. Accepts all parameters
    2727 *     of {@link bp_activity_add()}. The one difference is the following
    2828 *     argument, which has a different default here:
    2929 *     @type string $component Default: the id of your Friends component
    30  *           (usually 'friends').
     30 *                             (usually 'friends').
    3131 * }
    3232 * @return bool See {@link bp_activity_add()}.
     
    5959 * @param array $args {
    6060 *     An array of arguments for the item to delete.
    61  *     @type int $item_id ID of the 'item' associated with the activity item.
    62  *           For Friends activity items, this is usually the user ID of one
    63  *           of the friends.
    64  *     @type string $type The 'type' of the activity item (eg
    65  *           'friendship_accepted').
    66  *     @type int $user_id ID of the user associated with the activity item.
     61 *     @type int    $item_id ID of the 'item' associated with the activity item.
     62 *                           For Friends activity items, this is usually the user ID of one
     63 *                           of the friends.
     64 *     @type string $type    The 'type' of the activity item (eg
     65 *                           'friendship_accepted').
     66 *     @type int    $user_id ID of the user associated with the activity item.
    6767 * }
    6868 * @return bool True on success, false on failure.
     
    128128 * @since BuddyPress (2.0.0)
    129129 *
     130 * @param string $action   Activity action string.
    130131 * @param object $activity Activity data.
     132 *
    131133 * @return string $action Formatted activity action.
    132134 */
     
    150152     * @since BuddyPress (2.0.0)
    151153     *
    152      * @param string $action String text for the 'friendship_accepted' action.
     154     * @param string $action   String text for the 'friendship_accepted' action.
    153155     * @param object $activity Activity data.
    154156     */
     
    161163 * @since BuddyPress (2.0.0)
    162164 *
    163  * @param string $action Static activity action.
     165 * @param string $action   Static activity action.
    164166 * @param object $activity Activity data.
     167 *
    165168 * @return string $action Formatted activity action.
    166169 */
     
    184187     * @since BuddyPress (2.0.0)
    185188     *
    186      * @param string $action String text for the 'friendship_created' action.
     189     * @param string $action   String text for the 'friendship_created' action.
    187190     * @param object $activity Activity data.
    188191     */
     
    198201 *
    199202 * @param array $activities Array of activity items.
     203 *
    200204 * @return array
    201205 */
     
    237241 * @param array $retval Empty array by default
    238242 * @param array $filter Current activity arguments
     243 *
    239244 * @return array
    240245 */
     
    290295 * @param array $retval Empty array by default
    291296 * @param array $filter Current activity arguments
     297 *
    292298 * @return array
    293299 */
     
    364370 * @since BuddyPress (1.9.0)
    365371 *
    366  * @param int $friendship_id
    367  * @param int $initiator_user_id
    368  * @param int $friend_user_id
    369  * @param object $friendship Optional
     372 * @param int         $friendship_id
     373 * @param int         $initiator_user_id
     374 * @param int         $friend_user_id
     375 * @param object|bool $friendship Optional
    370376 */
    371377function bp_friends_friendship_accepted_activity( $friendship_id, $initiator_user_id, $friend_user_id, $friendship = false ) {
  • trunk/src/bp-friends/bp-friends-cache.php

    r9819 r9995  
    1818 *
    1919 * @param int $friendship_id ID of the friendship whose two members should
    20  *        have their friends cache busted.
     20 *                           have their friends cache busted.
     21 *
     22 * @return bool
    2123 */
    2224function friends_clear_friend_object_cache( $friendship_id ) {
     
    3739 * @since BuddyPress (2.0.0)
    3840 *
    39  * @param int $friend_user_id The user ID not initiating the friendship
     41 * @param int $friend_user_id The user ID not initiating the friendship.
    4042 */
    4143function bp_friends_clear_request_cache( $friend_user_id ) {
     
    5052 * @since BuddyPress (2.0.0)
    5153 *
    52  * @param int $friendship_id The friendship ID
    53  * @param int $initiator_user_id The user ID initiating the friendship
    54  * @param int $friend_user_id The user ID not initiating the friendship
     54 * @param int $friendship_id     The friendship ID.
     55 * @param int $initiator_user_id The user ID initiating the friendship.
     56 * @param int $friend_user_id    The user ID not initiating the friendship.
    5557 */
    5658function bp_friends_clear_request_cache_on_save( $friendship_id, $initiator_user_id, $friend_user_id ) {
     
    6769 * @since BuddyPress (2.0.0)
    6870 *
    69  * @param int $friendship_id The friendship ID
     71 * @param int                   $friendship_id The friendship ID.
    7072 * @param BP_Friends_Friendship $friendship
    7173 */
    7274function bp_friends_clear_request_cache_on_remove( $friendship_id, BP_Friends_Friendship $friendship ) {
    73     bp_friends_clear_request_cache( $friendship->friend_user_id ); 
     75    bp_friends_clear_request_cache( $friendship->friend_user_id );
    7476}
    7577add_action( 'friends_friendship_withdrawn', 'bp_friends_clear_request_cache_on_remove', 10, 2 );
  • trunk/src/bp-friends/bp-friends-classes.php

    r9819 r9995  
    11<?php
    22/**
    3  * BuddyPress Friends Classes
     3 * BuddyPress Friends Classes.
    44 *
    55 * @package BuddyPress
  • trunk/src/bp-friends/bp-friends-filters.php

    r9819 r9995  
    22
    33/**
    4  * BuddyPress Friend Filters
     4 * BuddyPress Friend Filters.
    55 *
    66 * @package BuddyPress
     
    1818 * @global WPDB $wpdb WordPress database access object.
    1919 *
    20  * @param BP_User_Query $user_query The BP_User_Query object.
    21  * @param string $user_ids_sql Comma-separated list of user IDs to fetch extra
    22  *        data for, as determined by BP_User_Query.
     20 * @param BP_User_Query $user_query   The BP_User_Query object.
     21 * @param string        $user_ids_sql Comma-separated list of user IDs to fetch extra
     22 *                                    data for, as determined by BP_User_Query.
    2323 */
    2424function bp_friends_filter_user_query_populate_extras( BP_User_Query $user_query, $user_ids_sql ) {
  • 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.
  • trunk/src/bp-friends/bp-friends-loader.php

    r9936 r9995  
    11<?php
    22/**
    3  * BuddyPress Friends Streams Loader
     3 * BuddyPress Friends Streams Loader.
    44 *
    55 * The friends component is for users to create relationships with each other.
     
    107107     *
    108108     * @param array $main_nav Optional. See BP_Component::setup_nav() for
    109      *        description.
    110      * @param array $sub_nav Optional. See BP_Component::setup_nav() for
    111      *        description.
     109     *                        description.
     110     * @param array $sub_nav  Optional. See BP_Component::setup_nav() for
     111     *                        description.
    112112     */
    113113    public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
     
    170170     *
    171171     * @param array $wp_admin_nav See BP_Component::setup_admin_bar()
    172      *        for description.
     172     *                            for description.
    173173     */
    174174    public function setup_admin_bar( $wp_admin_nav = array() ) {
     
    243243
    244244    /**
    245      * Setup cache groups
     245     * Setup cache groups.
    246246     *
    247247     * @since BuddyPress (2.2.0)
  • trunk/src/bp-friends/bp-friends-notifications.php

    r9819 r9995  
    22
    33/**
    4  * BuddyPress Friends Activity Functions
     4 * BuddyPress Friends Activity Functions.
    55 *
    66 * These functions handle the recording, deleting and formatting of activity
     
    2323 *
    2424 * @param int $friendship_id ID of the friendship object.
    25  * @param int $initiator_id ID of the user who initiated the request.
    26  * @param int $friend_id ID of the request recipient.
     25 * @param int $initiator_id  ID of the user who initiated the request.
     26 * @param int $friend_id     ID of the request recipient.
     27 *
     28 * @return bool
    2729 */
    2830function friends_notification_new_request( $friendship_id, $initiator_id, $friend_id ) {
     
    7173     * @since BuddyPress (1.2.0)
    7274     *
    73      * @param string $subject Subject line to be used in friend request email.
     75     * @param string $subject        Subject line to be used in friend request email.
    7476     * @param string $initiator_name Name of the person requesting friendship.
    7577     */
     
    8183     * @since BuddyPress (1.2.0)
    8284     *
    83      * @param string $message Message to be used in friend request email.
    84      * @param string $initiator_name Name of the person requesting friendship.
    85      * @param string $initiator_link Profile link of person requesting friendship.
     85     * @param string $message           Message to be used in friend request email.
     86     * @param string $initiator_name    Name of the person requesting friendship.
     87     * @param string $initiator_link    Profile link of person requesting friendship.
    8688     * @param string $all_requests_link User's friends request management link.
    87      * @param string $settings_link Email recipient's settings management link.
     89     * @param string $settings_link     Email recipient's settings management link.
    8890     */
    8991    $message = apply_filters( 'friends_notification_new_request_message', $message, $initiator_name, $initiator_link, $all_requests_link, $settings_link );
     
    9698     * @since BuddyPress (1.5.0)
    9799     *
    98      * @param int    $friend_id ID of the request recipient.
    99      * @param string $subject Text for the friend request subject field.
    100      * @param string $message Text for the friend request message field.
     100     * @param int    $friend_id     ID of the request recipient.
     101     * @param string $subject       Text for the friend request subject field.
     102     * @param string $message       Text for the friend request message field.
    101103     * @param int    $friendship_id ID of the friendship object.
    102      * @param int    $initiator_id ID of the friendship requester.
     104     * @param int    $initiator_id  ID of the friendship requester.
    103105     */
    104106    do_action( 'bp_friends_sent_request_email', $friend_id, $subject, $message, $friendship_id, $initiator_id );
     
    113115 *
    114116 * @param int $friendship_id ID of the friendship object.
    115  * @param int $initiator_id ID of the user who initiated the request.
    116  * @param int $friend_id ID of the request recipient.
     117 * @param int $initiator_id  ID of the user who initiated the request.
     118 * @param int $friend_id     ID of the request recipient.
     119 *
     120 * @return bool
    117121 */
    118122function friends_notification_accepted_request( $friendship_id, $initiator_id, $friend_id ) {
     
    158162     * @since BuddyPress (1.2.0)
    159163     *
    160      * @param string $subject Subject line to be used in friend request accepted email.
     164     * @param string $subject     Subject line to be used in friend request accepted email.
    161165     * @param string $friend_name Name of the person who accepted the friendship request.
    162166     */
     
    168172     * @since BuddyPress (1.2.0)
    169173     *
    170      * @param string $message Message to be used in friend request email.
    171      * @param string $friend_name Name of the person who accepted the friendship request.
    172      * @param string $friend_link Profile link of person who accepted the friendship request.
     174     * @param string $message       Message to be used in friend request email.
     175     * @param string $friend_name   Name of the person who accepted the friendship request.
     176     * @param string $friend_link   Profile link of person who accepted the friendship request.
    173177     * @param string $settings_link Email recipient's settings management link.
    174178     */
     
    182186     * @since BuddyPress (1.5.0)
    183187     *
    184      * @param int    $initiator_id ID of the friendship requester.
    185      * @param string $subject Text for the friend request subject field.
    186      * @param string $message Text for the friend request message field.
     188     * @param int    $initiator_id  ID of the friendship requester.
     189     * @param string $subject       Text for the friend request subject field.
     190     * @param string $message       Text for the friend request message field.
    187191     * @param int    $friendship_id ID of the friendship object.
    188      * @param int    $friend_id ID of the request recipient.
     192     * @param int    $friend_id     ID of the request recipient.
    189193     */
    190194    do_action( 'bp_friends_sent_accepted_email', $initiator_id, $subject, $message, $friendship_id, $friend_id );
     
    197201 * Notification formatting callback for bp-friends notifications.
    198202 *
    199  * @param string $action The kind of notification being rendered.
    200  * @param int $item_id The primary item ID.
    201  * @param int $secondary_item_id The secondary item ID.
    202  * @param int $total_items The total number of messaging-related notifications
    203  *        waiting for the user.
    204  * @param string $format 'string' for BuddyBar-compatible notifications;
    205  *        'array' for WP Toolbar. Default: 'string'.
     203 * @param string $action            The kind of notification being rendered.
     204 * @param int    $item_id           The primary item ID.
     205 * @param int    $secondary_item_id The secondary item ID.
     206 * @param int    $total_items       The total number of messaging-related notifications
     207 *                                  waiting for the user.
     208 * @param string $format            'string' for BuddyBar-compatible notifications;
     209 *                                  'array' for WP Toolbar. Default: 'string'.
     210 *
    206211 * @return array|string
    207212 */
     
    328333 *
    329334 * @since BuddyPress (1.9.0)
    330  * @param int $friendship_id The unique ID of the friendship
    331  * @param int $initiator_user_id The friendship initiator user ID
    332  * @param int $friend_user_id The friendship request receiver user ID
     335 * @param int $friendship_id     The unique ID of the friendship.
     336 * @param int $initiator_user_id The friendship initiator user ID.
     337 * @param int $friend_user_id    The friendship request receiver user ID.
    333338 */
    334339function bp_friends_friendship_requested_notification( $friendship_id, $initiator_user_id, $friend_user_id ) {
     
    352357 * @since BuddyPress (1.9.0)
    353358 *
    354  * @param int $friendship_id (not used)
     359 * @param int    $friendship_id (not used)
    355360 * @param object $friendship
    356361 */
     
    366371 *
    367372 * @since BuddyPress (1.9.0)
    368  * @param int $friendship_id The unique ID of the friendship
    369  * @param int $initiator_user_id The friendship initiator user ID
    370  * @param int $friend_user_id The friendship request receiver user ID
     373 *
     374 * @param int $friendship_id     The unique ID of the friendship.
     375 * @param int $initiator_user_id The friendship initiator user ID.
     376 * @param int $friend_user_id    The friendship request receiver user ID.
    371377 */
    372378function bp_friends_add_friendship_accepted_notification( $friendship_id, $initiator_user_id, $friend_user_id ) {
     
    394400
    395401/**
    396  * Remove friend request notice when a member withdraws their friend request
    397  *
    398  * @since BuddyPress (1.9.0)
    399  *
    400  * @param int $friendship_id (not used)
     402 * Remove friend request notice when a member withdraws their friend request.
     403 *
     404 * @since BuddyPress (1.9.0)
     405 *
     406 * @param int    $friendship_id (not used)
    401407 * @param object $friendship
    402408 */
     
    409415
    410416/**
    411  * Remove friendship requests FROM user, used primarily when a user is deleted
    412  *
    413  * @since BuddyPress (1.9.0)
     417 * Remove friendship requests FROM user, used primarily when a user is deleted.
     418 *
     419 * @since BuddyPress (1.9.0)
     420 *
    414421 * @param int $user_id
    415422 */
  • trunk/src/bp-friends/bp-friends-screens.php

    r9819 r9995  
    22
    33/**
    4  * BuddyPress Friends Screen Functions
     4 * BuddyPress Friends Screen Functions.
    55 *
    66 * Screen functions are the controllers of BuddyPress. They will execute when
  • trunk/src/bp-friends/bp-friends-template.php

    r9819 r9995  
    263263     *
    264264     * @param int $user_id Optional. If provided, the function will simply
    265      *        return this value.
     265     *                     return this value.
     266     *
    266267     * @return int ID of potential friend.
    267268     */
     
    290291 *
    291292 * @param int $user_id ID of the potential friend. Default: the value of
    292  *        {@link bp_get_potential_friend_id()}.
     293 *                     {@link bp_get_potential_friend_id()}.
     294 *
    293295 * @return string 'is_friend', 'not_friends', or 'pending'.
    294296 */
     
    319321 * @see bp_get_add_friend_button() for information on arguments.
    320322 *
    321  * @param int $potential_friend_id See {@link bp_get_add_friend_button()}.
    322  * @param int $friend_status See {@link bp_get_add_friend_button()}.
     323 * @param int      $potential_friend_id See {@link bp_get_add_friend_button()}.
     324 * @param int|bool $friend_status      See {@link bp_get_add_friend_button()}.
    323325 */
    324326function bp_add_friend_button( $potential_friend_id = 0, $friend_status = false ) {
     
    328330     * Create the Add Friend button.
    329331     *
    330      * @param int $potential_friend_id ID of the user to whom the button
    331      *        applies. Default: value of {@link bp_get_potential_friend_id()}.
    332      * @param bool $friend_status Not currently used.
     332     * @param int  $potential_friend_id ID of the user to whom the button
     333     *                                  applies. Default: value of {@link bp_get_potential_friend_id()}.
     334     * @param bool $friend_status       Not currently used.
     335     *
    333336     * @return string HTML for the Add Friend button.
    334337     */
     
    427430 *
    428431 * @param int $user_id Optional. Default: the displayed user's ID, or the
    429  *        logged-in user's ID.
     432 *                     logged-in user's ID.
     433 *
    430434 * @return string|bool A comma-separated list of friend IDs if any are found,
    431  *         otherwise false.
     435 *                     otherwise false.
    432436 */
    433437function bp_get_friend_ids( $user_id = 0 ) {
     
    451455 *
    452456 * @param int $user_id ID of the user whose requests are being retrieved.
    453  *        Defaults to displayed user.
     457 *                     Defaults to displayed user.
     458 *
    454459 * @return array|int An array of user IDs if found, or a 0 if none are found.
    455460 */
     
    580585     *
    581586     * @param int $user_id See {@link friends_get_total_friend_count()}.
     587     *
    582588     * @return int Total friend count.
    583589     */
     
    609615     *
    610616     * @param int $user_id ID of the user whose requests are being counted.
    611      *        Default: ID of the logged-in user.
     617     *                     Default: ID of the logged-in user.
     618     *
    612619     * @return int Friend count.
    613620     */
     
    633640 * @since BuddyPress (2.0.0)
    634641 *
    635  * @param array $args before|after|user_id
    636  * @uses bp_friends_get_profile_stats() to get the stats
     642 * @uses bp_friends_get_profile_stats() to get the stats.
     643 *
     644 * @param array|string $args before|after|user_id
    637645 */
    638646function bp_friends_profile_stats( $args = '' ) {
     
    646654 * @since BuddyPress (2.0.0)
    647655 *
    648  * @param array $args before|after|user_id
     656 * @param array|string $args before|after|user_id
     657 *
    649658 * @return string HTML for stats output.
    650659 */
     
    682691     *
    683692     * @param string $value Formatted string displaying total friends count.
    684      * @param array  $r Array of arguments for string formatting and output.
     693     * @param array  $r     Array of arguments for string formatting and output.
    685694     */
    686695    return apply_filters( 'bp_friends_get_profile_stats', $r['output'], $r );
  • trunk/src/bp-friends/bp-friends-widgets.php

    r9819 r9995  
    11<?php
    22/**
    3  * BuddyPress Widgets
     3 * BuddyPress Widgets.
    44 *
    55 * @package BuddyPress
     
    157157     * @param array $new_instance The parameters saved by the user.
    158158     * @param array $old_instance The parameters as previously saved to the database.
     159     *
    159160     * @return array $instance The processed settings to save.
    160161     */
     
    173174     *
    174175     * @param array $instance The saved widget settings.
     176     *
     177     * @return string
    175178     */
    176179    function form( $instance ) {
  • trunk/src/bp-friends/classes/class-bp-friends-friendship.php

    r9985 r9995  
    11<?php
    22/**
    3  * BuddyPress Friends Classes
     3 * BuddyPress Friends Classes.
    44 *
    55 * @package BuddyPress
     
    7171     *
    7272     * @access public
    73      * @var unknown
     73     * @var bool
    7474     */
    7575    public $is_request;
     
    9494     * Constructor method.
    9595     *
    96      * @param int $id Optional. The ID of an existing friendship.
    97      * @param bool $is_request Deprecated.
    98      * @param bool $populate_friend_details True if friend details should
    99      *        be queried.
     96     * @param int  $id                      Optional. The ID of an existing friendship.
     97     * @param bool $is_request              Deprecated.
     98     * @param bool $populate_friend_details True if friend details should be queried.
    10099     */
    101100    public function __construct( $id = null, $is_request = false, $populate_friend_details = true ) {
     
    194193     * Get the IDs of a given user's friends.
    195194     *
    196      * @param int $user_id ID of the user whose friends are being retrieved.
     195     * @param int  $user_id              ID of the user whose friends are being retrieved.
    197196     * @param bool $friend_requests_only Optional. Whether to fetch
    198      *        unaccepted requests only. Default: false.
    199      * @param bool $assoc_arr Optional. True to receive an array of arrays
    200      *        keyed as 'user_id' => $user_id; false to get a one-dimensional
    201      *        array of user IDs. Default: false.
     197     *                                   unaccepted requests only. Default: false.
     198     * @param bool $assoc_arr            Optional. True to receive an array of arrays
     199     *                                   keyed as 'user_id' => $user_id; false to get a one-dimensional
     200     *                                   array of user IDs. Default: false.
     201     *
     202     * @return array $fids IDs of friends for provided user.
    202203     */
    203204    public static function get_friend_user_ids( $user_id, $friend_requests_only = false, $assoc_arr = false ) {
     
    230231     * Get the ID of the friendship object, if any, between a pair of users.
    231232     *
    232      * @param int $user_id The ID of the first user.
     233     * @param int $user_id   The ID of the first user.
    233234     * @param int $friend_id The ID of the second user.
    234      * @return int|bool The ID of the friendship object if found, otherwise
    235      *         false.
     235     *
     236     * @return int|bool The ID of the friendship object if found, otherwise false.
    236237     */
    237238    public static function get_friendship_id( $user_id, $friend_id ) {
     
    247248     *
    248249     * @param int $user_id The ID of the user who has received the
    249      *        friendship requests.
     250     *                     friendship requests.
     251     *
    250252     * @return array|bool An array of user IDs, or false if none are found.
    251253     */
     
    270272     *
    271273     * @param int $user_id Optional. ID of the user whose friendships you
    272      *        are counting. Default: displayed user (if any), otherwise
    273      *        logged-in user.
     274     *                     are counting. Default: displayed user (if any), otherwise
     275     *                     logged-in user.
     276     *
    274277     * @return int Friend count for the user.
    275278     */
     
    299302     * Search the friends of a user by a search string.
    300303     *
    301      * @param string $filter The search string, matched against xprofile
    302      *        fields (if available), or usermeta 'nickname' field.
    303      * @param int $user_id ID of the user whose friends are being searched.
    304      * @param int $limit Optional. Max number of friends to return.
    305      * @param int $page Optional. The page of results to return. Default:
    306      *        null (no pagination - return all results).
     304     * @param string $filter  The search string, matched against xprofile
     305     *                        fields (if available), or usermeta 'nickname' field.
     306     * @param int    $user_id ID of the user whose friends are being searched.
     307     * @param int    $limit   Optional. Max number of friends to return.
     308     * @param int    $page    Optional. The page of results to return. Default:
     309     *                        null (no pagination - return all results).
     310     *
    307311     * @return array|bool On success, an array: {
    308312     *     @type array $friends IDs of friends returned by the query.
    309      *     @type int $count Total number of friends (disregarding
    310      *           pagination) who match the search.
     313     *     @type int   $count  Total number of friends (disregarding
     314     *                          pagination) who match the search.
    311315     * }. Returns false on failure.
    312316     */
     
    364368     * sent the initial request)
    365369     *
    366      * @param int $initiator_userid The ID of the user who is the initiator
    367      *        of the potential friendship/request.
     370     * @param int $initiator_userid       The ID of the user who is the initiator
     371     *                                    of the potential friendship/request.
    368372     * @param int $possible_friend_userid The ID of the user who is the
    369      *        recipient of the potential friendship/request.
    370      * @return string The friendship status, from among 'not_friends',
    371      *        'is_friend', 'pending', and 'awaiting_response'.
     373     *                                    recipient of the potential friendship/request.
     374     *
     375     * @return string $value The friendship status, from among 'not_friends',
     376     *                       'is_friend', 'pending', and 'awaiting_response'.
    372377     */
    373378    public static function check_is_friend( $initiator_userid, $possible_friend_userid ) {
     
    401406     *
    402407     * @param array $user_ids IDs of users whose last_active meta is
    403      *        being queried.
    404      * @return array Array of last_active values + user_ids.
     408     *                        being queried.
     409     *
     410     * @return array $retval Array of last_active values + user_ids.
    405411     */
    406412    public static function get_bulk_last_active( $user_ids ) {
     
    434440     *
    435441     * @param int $friendship_id ID of the friendship to be accepted.
     442     *
    436443     * @return int Number of database rows updated.
    437444     */
     
    448455     *
    449456     * @param int $friendship_id ID of the friendship to be withdrawn.
     457     *
    450458     * @return int Number of database rows deleted.
    451459     */
     
    462470     *
    463471     * @param int $friendship_id ID of the friendship to be rejected.
     472     *
    464473     * @return int Number of database rows deleted.
    465474     */
     
    477486     * @todo Why does this exist, and why is it in bp-friends?
    478487     *
    479      * @param string $filter String to search by.
    480      * @param int $user_id A user ID param that is unused.
    481      * @param int $limit Optional. Max number of records to return.
    482      * @param int $page Optional. Number of the page to return. Default:
    483      *        false (no pagination - return all results).
     488     * @param string $filter  String to search by.
     489     * @param int    $user_id A user ID param that is unused.
     490     * @param int    $limit   Optional. Max number of records to return.
     491     * @param int    $page    Optional. Number of the page to return. Default:
     492     *                        false (no pagination - return all results).
     493     *
    484494     * @return array $filtered_ids IDs of users who match the query.
    485495     */
     
    521531     *
    522532     * @param string $filter Search term.
     533     *
    523534     * @return int Count of users matching the search term.
    524535     */
     
    556567     *
    557568     * @param array $user_ids Array of user IDs.
     569     *
    558570     * @return array User IDs, sorted by the associated display names.
    559571     */
     
    574586     * Get a list of random friend IDs.
    575587     *
    576      * @param int $user_id ID of the user whose friends are being retrieved.
     588     * @param int $user_id       ID of the user whose friends are being retrieved.
    577589     * @param int $total_friends Optional. Number of random friends to get.
    578      *        Default: 5.
     590     *                           Default: 5.
     591     *
    579592     * @return array|bool An array of random friend user IDs on success;
    580      *         false if none are found.
     593     *                    false if none are found.
    581594     */
    582595    public static function get_random_friends( $user_id, $total_friends = 5 ) {
     
    608621     * - users who have been banned from the group
    609622     *
    610      * @param int $user_id ID of the user whose friends are being counted.
     623     * @param int $user_id  ID of the user whose friends are being counted.
    611624     * @param int $group_id ID of the group friends are being invited to.
     625     *
    612626     * @return int $invitable_count Eligible friend count.
    613627     */
     
    643657     *
    644658     * @param int $friendship_id ID of the friendship.
     659     *
    645660     * @return object friend_user_id and initiator_user_id.
    646661     */
Note: See TracChangeset for help on using the changeset viewer.