Skip to:
Content

BuddyPress.org

Changeset 10587


Ignore:
Timestamp:
02/13/2016 07:32:53 PM (9 years ago)
Author:
tw2113
Message:

Addes missing @since tags to many functions, methods, and properties in the BP Friends component.

See #6400.

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

Legend:

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

    r10417 r10587  
    1717/**
    1818 * Catch and process friendship requests.
     19 *
     20 * @since 1.0.1
    1921 */
    2022function friends_action_add_friend() {
     
    5557/**
    5658 * Catch and process Remove Friendship requests.
     59 *
     60 * @since 1.0.1
    5761 */
    5862function friends_action_remove_friend() {
  • trunk/src/bp-friends/bp-friends-activity.php

    r10563 r10587  
    1919 * A wrapper for {@link bp_activity_add()} that provides some Friends-specific
    2020 * defaults.
     21 *
     22 * @since 1.0.0
    2123 *
    2224 * @see bp_activity_add() for more detailed description of parameters and
     
    5759 * Delete an activity item related to the Friends component.
    5860 *
     61 * @since 1.0.0
     62 *
    5963 * @param array $args {
    6064 *     An array of arguments for the item to delete.
     
    8387/**
    8488 * Register the activity actions for bp-friends.
     89 *
     90 * @since 1.1.0
    8591 */
    8692function friends_register_activity_actions() {
     
    291297 * @param array $retval Empty array by default.
    292298 * @param array $filter Current activity arguments.
    293  *
    294299 * @return array
    295300 */
  • trunk/src/bp-friends/bp-friends-cache.php

    r10417 r10587  
    1616/**
    1717 * Clear friends-related cache for members of a specific friendship.
     18 *
     19 * @since 1.0.0
    1820 *
    1921 * @param int $friendship_id ID of the friendship whose two members should
  • trunk/src/bp-friends/bp-friends-functions.php

    r10417 r10587  
    1818/**
    1919 * Create a new friendship.
     20 *
     21 * @since 1.0.0
    2022 *
    2123 * @param int  $initiator_userid ID of the "initiator" user (the user who is
     
    9193 * Will also delete the related "friendship_accepted" activity item.
    9294 *
     95 * @since 1.0.0
     96 *
    9397 * @param int $initiator_userid ID of the friendship initiator.
    9498 * @param int $friend_userid    ID of the friend user.
     
    152156 *
    153157 * Also initiates a "friendship_accepted" activity item.
     158 *
     159 * @since 1.0.0
    154160 *
    155161 * @param int $friendship_id ID of the pending friendship object.
     
    188194 * Mark a friendship request as rejected.
    189195 *
     196 * @since 1.0.0
     197 *
    190198 * @param int $friendship_id ID of the pending friendship object.
    191199 * @return bool True on success, false on failure.
     
    214222 * Withdraw a friendship request.
    215223 *
     224 * @since 1.6.0
     225 *
    216226 * @param int $initiator_userid ID of the friendship initiator - this is the
    217227 *                              user who requested the friendship, and is doing the withdrawing.
     
    247257 * Check whether two users are friends.
    248258 *
     259 * @since 1.0.0
     260 *
    249261 * @param int $user_id            ID of the first user.
    250262 * @param int $possible_friend_id ID of the other user.
     
    263275 *
    264276 * Will return 'is_friends', 'not_friends', 'pending' or 'awaiting_response'.
     277 *
     278 * @since 1.2.0
    265279 *
    266280 * @param int $user_id            ID of the first user.
     
    285299 * Get the friend count of a given user.
    286300 *
     301 * @since 1.2.0
     302 *
    287303 * @param int $user_id ID of the user whose friends are being counted.
    288304 * @return int Friend count of the user.
     
    309325 * Check whether a given user has any friends.
    310326 *
     327 * @since 1.0.0
     328 *
    311329 * @param int $user_id ID of the user whose friends are being checked.
    312330 * @return bool True if the user has friends, otherwise false.
     
    326344/**
    327345 * Get the ID of two users' friendship, if it exists.
     346 *
     347 * @since 1.2.0
    328348 *
    329349 * @param int $initiator_user_id ID of the first user.
     
    337357/**
    338358 * Get the IDs of a given user's friends.
     359 *
     360 * @since 1.0.0
    339361 *
    340362 * @param int  $user_id              ID of the user whose friends are being retrieved.
     
    352374/**
    353375 * Search the friends of a user by a search string.
     376 *
     377 * @since 1.0.0
    354378 *
    355379 * @param string $search_terms The search string, matched against xprofile fields (if
     
    372396 * Get a list of IDs of users who have requested friendship of a given user.
    373397 *
     398 * @since 1.2.0
     399 *
    374400 * @param int $user_id The ID of the user who has received the friendship requests.
    375401 * @return array|bool An array of user IDs, or false if none are found.
     
    381407/**
    382408 * Get a user's most recently active friends.
     409 *
     410 * @since 1.0.0
    383411 *
    384412 * @see BP_Core_User::get_users() for a description of return value.
     
    411439 * Get a user's friends, in alphabetical order.
    412440 *
     441 * @since 1.0.0
     442 *
    413443 * @see BP_Core_User::get_users() for a description of return value.
    414444 *
     
    440470 * Get a user's friends, in the order in which they joined the site.
    441471 *
     472 * @since 1.0.0
     473 *
    442474 * @see BP_Core_User::get_users() for a description of return value.
    443475 *
     
    469501 * Get the last active date of many users at once.
    470502 *
     503 * @since 1.0.0
     504 *
    471505 * @see BP_Friends_Friendship::get_bulk_last_active() for a description of
    472506 *      arguments and return value.
     
    578612 * - users who have been banned from the group
    579613 *
     614 * @since 1.0.0
     615 *
    580616 * @param int $user_id  ID of the user whose friends are being counted.
    581617 * @param int $group_id ID of the group friends are being invited to.
     
    589625 * Get a total friend count for a given user.
    590626 *
     627 * @since 1.0.0
     628 *
    591629 * @param int $user_id Optional. ID of the user whose friendships you are
    592630 *                     counting. Default: displayed user (if any), otherwise logged-in user.
     
    599637/**
    600638 * Return a list of a user's friends, filtered by a search term.
     639 *
     640 * @since 1.0.0
    601641 *
    602642 * @param string $search_terms Search term to filter on.
     
    625665 * Has a friendship been confirmed (accepted)?
    626666 *
     667 * @since 1.0.0
     668 *
    627669 * @param int $friendship_id The ID of the friendship being checked.
    628670 * @return bool True if the friendship is confirmed, otherwise false.
     
    639681 * friendship event (acceptance, deletion), call this function to regenerate
    640682 * the cached values.
     683 *
     684 * @since 1.0.0
    641685 *
    642686 * @param int    $initiator_user_id ID of the first user.
     
    666710 * - Notifications of friendship requests sent by the user.
    667711 *
     712 * @since 1.0.0
     713 *
    668714 * @param int $user_id ID of the user whose friend data is being removed.
    669715 */
     
    701747 *
    702748 * This is intended to speed up @mentions lookups for a majority of use cases.
     749 *
     750 * @since 2.1.0
    703751 *
    704752 * @see bp_activity_mentions_script()
  • trunk/src/bp-friends/bp-friends-loader.php

    r10519 r10587  
    1717/**
    1818 * Set up the bp-forums component.
     19 *
     20 * @since 1.6.0
    1921 */
    2022function bp_setup_friends() {
  • trunk/src/bp-friends/bp-friends-notifications.php

    r10479 r10587  
    2222 * the user of whom friendship has been requested ($friend_id).
    2323 *
    24  * @since 1.0
     24 * @since 1.0.0
    2525 *
    2626 * @param int $friendship_id ID of the friendship object.
     
    5353 * sent to the user who requested the friendship ($initiator_id).
    5454 *
    55  * @since 1.0
     55 * @since 1.0.0
    5656 *
    5757 * @param int $friendship_id ID of the friendship object.
     
    8181/**
    8282 * Notification formatting callback for bp-friends notifications.
     83 *
     84 * @since 1.0.0
    8385 *
    8486 * @param string $action            The kind of notification being rendered.
     
    177179/**
    178180 * Clear friend-related notifications when ?new=1
     181 *
     182 * @since 1.2.0
    179183 */
    180184function friends_clear_friend_notifications() {
  • trunk/src/bp-friends/bp-friends-screens.php

    r10417 r10587  
    1717/**
    1818 * Catch and process the My Friends page.
     19 *
     20 * @since 1.0.0
    1921 */
    2022function friends_screen_my_friends() {
     
    3941/**
    4042 * Catch and process the Requests page.
     43 *
     44 * @since 1.0.0
    4145 */
    4246function friends_screen_requests() {
     
    9498/**
    9599 * Add Friends-related settings to the Settings > Notifications page.
     100 *
     101 * @since 1.0.0
    96102 */
    97103function friends_screen_notification_settings() {
  • trunk/src/bp-friends/bp-friends-template.php

    r10424 r10587  
    219219/**
    220220 * Output the friend count for the current member in the loop.
     221 *
     222 * @since 1.2.0
    221223 */
    222224function bp_member_total_friend_count() {
     
    227229     *
    228230     * Return value is a string of the form "x friends".
     231     *
     232     * @since 1.2.0
    229233     *
    230234     * @return string A string of the form "x friends".
     
    254258 * Output the ID of the current user in the friend request loop.
    255259 *
     260 * @since 1.2.6
     261 *
    256262 * @see bp_get_potential_friend_id() for a description of arguments.
    257263 *
     
    263269    /**
    264270     * Return the ID of current user in the friend request loop.
     271     *
     272     * @since 1.2.6
    265273     *
    266274     * @global object $friends_template
     
    293301 * Returns - 'is_friend', 'not_friends', 'pending'.
    294302 *
     303 * @since 1.2.6
     304 *
    295305 * @param int $user_id ID of the potential friend. Default: the value of
    296306 *                     {@link bp_get_potential_friend_id()}.
     
    321331 * Output the Add Friend button.
    322332 *
     333 * @since 1.0.0
     334 *
    323335 * @see bp_get_add_friend_button() for information on arguments.
    324336 *
     
    331343    /**
    332344     * Create the Add Friend button.
     345     *
     346     * @since 1.1.0
    333347     *
    334348     * @param int  $potential_friend_id ID of the user to whom the button
     
    430444 * Get a comma-separated list of IDs of a user's friends.
    431445 *
     446 * @since 1.2.0
     447 *
    432448 * @param int $user_id Optional. Default: the displayed user's ID, or the
    433449 *                     logged-in user's ID.
     
    454470 * because of the structure of the $include parameter in bp_has_members().
    455471 *
     472 * @since 1.2.0
     473 *
    456474 * @param int $user_id ID of the user whose requests are being retrieved.
    457475 *                     Defaults to displayed user.
     
    487505/**
    488506 * Output the ID of the friendship between the logged-in user and the current user in the loop.
     507 *
     508 * @since 1.2.0
    489509 */
    490510function bp_friend_friendship_id() {
     
    493513    /**
    494514     * Return the ID of the friendship between the logged-in user and the current user in the loop.
     515     *
     516     * @since 1.2.0
    495517     *
    496518     * @return int ID of the friendship.
     
    516538/**
    517539 * Output the URL for accepting the current friendship request in the loop.
     540 *
     541 * @since 1.0.0
    518542 */
    519543function bp_friend_accept_request_link() {
     
    522546    /**
    523547     * Return the URL for accepting the current friendship request in the loop.
     548     *
     549     * @since 1.0.0
    524550     *
    525551     * @return string accept-friendship URL.
     
    545571/**
    546572 * Output the URL for rejecting the current friendship request in the loop.
     573 *
     574 * @since 1.0.0
    547575 */
    548576function bp_friend_reject_request_link() {
     
    551579    /**
    552580     * Return the URL for rejecting the current friendship request in the loop.
     581     *
     582     * @since 1.0.0
    553583     *
    554584     * @return string reject-friendship URL.
     
    575605 * Output the total friend count for a given user.
    576606 *
     607 * @since 1.2.0
     608 *
    577609 * @param int $user_id See {@link friends_get_total_friend_count()}.
    578610 */
     
    583615     * Return the total friend count for a given user.
    584616     *
     617     * @since 1.2.0
     618     *
    585619     * @param int $user_id See {@link friends_get_total_friend_count()}.
    586620     * @return int Total friend count.
     
    602636 * Output the total friendship request count for a given user.
    603637 *
     638 * @since 1.2.0
     639 *
    604640 * @see bp_friend_get_total_requests_count() for description of arguments.
    605641 *
     
    611647    /**
    612648     * Return the total friendship request count for a given user.
     649     *
     650     * @since 1.2.0
    613651     *
    614652     * @param int $user_id ID of the user whose requests are being counted.
  • trunk/src/bp-friends/classes/class-bp-core-friends-widget.php

    r10553 r10587  
    2020    /**
    2121     * Class constructor.
     22     *
     23     * @since 1.9.0
    2224     */
    2325    function __construct() {
     
    3234    /**
    3335     * Display the widget.
     36     *
     37     * @since 1.9.0
    3438     *
    3539     * @param array $args Widget arguments.
     
    139143     * Process a widget save.
    140144     *
     145     * @since 1.9.0
     146     *
    141147     * @param array $new_instance The parameters saved by the user.
    142148     * @param array $old_instance The parameters as previously saved to the database.
     
    155161    /**
    156162     * Render the widget edit form.
     163     *
     164     * @since 1.9.0
    157165     *
    158166     * @param array $instance The saved widget settings.
  • trunk/src/bp-friends/classes/class-bp-friends-component.php

    r10555 r10587  
    1515/**
    1616 * Defines the BuddyPress Friends Component.
     17 *
     18 * @since 1.5.0
    1719 */
    1820class BP_Friends_Component extends BP_Component {
     
    3638    /**
    3739     * Include bp-friends files.
     40     *
     41     * @since 1.5.0
    3842     *
    3943     * @see BP_Component::includes() for description of parameters.
     
    226230    /**
    227231     * Set up the title for pages and <title>.
     232     *
     233     * @since 1.5.0
    228234     */
    229235    public function setup_title() {
  • trunk/src/bp-friends/classes/class-bp-friends-friendship.php

    r10424 r10587  
    1313/**
    1414 * BuddyPress Friendship object.
     15 *
     16 * @since 1.0.0
    1517 */
    1618class BP_Friends_Friendship {
     
    1921     * ID of the friendship.
    2022     *
     23     * @since 1.0.0
    2124     * @var int
    2225     */
     
    2629     * User ID of the friendship initiator.
    2730     *
     31     * @since 1.0.0
    2832     * @var int
    2933     */
     
    3337     * User ID of the 'friend' - the one invited to the friendship.
    3438     *
     39     * @since 1.0.0
    3540     * @var int
    3641     */
     
    4045     * Has the friendship been confirmed/accepted?
    4146     *
     47     * @since 1.0.0
    4248     * @var int
    4349     */
     
    4955     * Not currently used by BuddyPress.
    5056     *
     57     * @since 1.0.0
    5158     * @var int
    5259     */
     
    5663     * Date the friendship was created.
    5764     *
     65     * @since 1.0.0
    5866     * @var string
    5967     */
     
    6573     * Not currently used in BuddyPress.
    6674     *
     75     * @since 1.0.0
    6776     * @var bool
    6877     */
     
    7281     * Should additional friend details be queried?
    7382     *
     83     * @since 1.0.0
    7484     * @var bool
    7585     */
     
    7989     * Details about the friend.
    8090     *
     91     * @since 1.0.0
    8192     * @var BP_Core_User
    8293     */
     
    8596    /**
    8697     * Constructor method.
     98     *
     99     * @since 1.5.0
    87100     *
    88101     * @param int|null $id                      Optional. The ID of an existing friendship.
     
    102115    /**
    103116     * Set up data about the current friendship.
     117     *
     118     * @since 1.0.0
    104119     */
    105120    public function populate() {
     
    127142    /**
    128143     * Save the current friendship to the database.
     144     *
     145     * @since 1.0.0
    129146     *
    130147     * @return bool True on success, false on failure.
     
    175192     * Delete the current friendship from the database.
    176193     *
     194     * @since 1.0.0
     195     *
    177196     * @return bool|int
    178197     */
     
    189208    /**
    190209     * Get the IDs of a given user's friends.
     210     *
     211     * @since 1.0.0
    191212     *
    192213     * @param int  $user_id              ID of the user whose friends are being retrieved.
     
    227248     * Get the ID of the friendship object, if any, between a pair of users.
    228249     *
     250     * @since 1.0.0
     251     *
    229252     * @param int $user_id   The ID of the first user.
    230253     * @param int $friend_id The ID of the second user.
     
    242265     * Get a list of IDs of users who have requested friendship of a given user.
    243266     *
     267     * @since 1.2.0
     268     *
    244269     * @param int $user_id The ID of the user who has received the
    245270     *                     friendship requests.
     
    264289    /**
    265290     * Get a total friend count for a given user.
     291     *
     292     * @since 1.0.0
    266293     *
    267294     * @param int $user_id Optional. ID of the user whose friendships you
     
    296323    /**
    297324     * Search the friends of a user by a search string.
     325     *
     326     * @since 1.0.0
    298327     *
    299328     * @param string   $filter  The search string, matched against xprofile
     
    303332     * @param int|null $page    Optional. The page of results to return. Default:
    304333     *                          null (no pagination - return all results).
    305      *
    306334     * @return array|bool On success, an array: {
    307335     *     @type array $friends IDs of friends returned by the query.
     
    364392     * while 'awaiting_response' is the other way around ($possible_friend_userid
    365393     * sent the initial request).
     394     *
     395     * @since 1.0.0
    366396     *
    367397     * @param int $initiator_userid       The ID of the user who is the initiator
     
    401431     * @todo Why is this in the Friends component?
    402432     *
     433     * @since 1.0.0
     434     *
    403435     * @param array $user_ids IDs of users whose last_active meta is
    404436     *                        being queried.
     
    434466     * Mark a friendship as accepted.
    435467     *
     468     * @since 1.0.0
     469     *
    436470     * @param int $friendship_id ID of the friendship to be accepted.
    437471     * @return int Number of database rows updated.
     
    448482     * Remove a friendship or a friendship request INITIATED BY the logged-in user.
    449483     *
     484     * @since 1.6.0
     485     *
    450486     * @param int $friendship_id ID of the friendship to be withdrawn.
    451487     * @return int Number of database rows deleted.
     
    462498     * Remove a friendship or a friendship request MADE OF the logged-in user.
    463499     *
     500     * @since 1.0.0
     501     *
    464502     * @param int $friendship_id ID of the friendship to be rejected.
    465503     * @return int Number of database rows deleted.
     
    477515     *
    478516     * @todo Why does this exist, and why is it in bp-friends?
     517     *
     518     * @since 1.0.0
    479519     *
    480520     * @param string   $filter  String to search by.
     
    521561     * @todo Why does this exist, and why is it in bp-friends?
    522562     *
     563     * @since 1.0.0
     564     *
    523565     * @param string $filter Search term.
    524566     * @return int Count of users matching the search term.
     
    556598     * @todo Why does this exist, and why is it in bp-friends?
    557599     *
     600     * @since 1.0.0
     601     *
    558602     * @param array $user_ids Array of user IDs.
    559603     * @return array User IDs, sorted by the associated display names.
     
    574618    /**
    575619     * Get a list of random friend IDs.
     620     *
     621     * @since 1.0.0
    576622     *
    577623     * @param int $user_id       ID of the user whose friends are being retrieved.
     
    609655     * - users who have been banned from the group
    610656     *
     657     * @since 1.0.0
     658     *
    611659     * @param int $user_id  ID of the user whose friends are being counted.
    612660     * @param int $group_id ID of the group friends are being invited to.
     
    643691     * Get the friend user IDs for a given friendship.
    644692     *
     693     * @since 1.0.0
     694     *
    645695     * @param int $friendship_id ID of the friendship.
    646696     * @return object friend_user_id and initiator_user_id.
     
    656706    /**
    657707     * Delete all friendships and friend notifications related to a user.
     708     *
     709     * @since 1.0.0
    658710     *
    659711     * @param int $user_id ID of the user being expunged.
Note: See TracChangeset for help on using the changeset viewer.