Skip to:
Content

BuddyPress.org

Changeset 7560


Ignore:
Timestamp:
11/11/2013 02:03:09 AM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-friends component. See #5022

Location:
trunk/bp-friends
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-friends/bp-friends-screens.php

    r7537 r7560  
    44 * BuddyPress Friends Screen Functions
    55 *
    6  * Screen functions are the controllers of BuddyPress. They will execute when their
    7  * specific URL is caught. They will first save or manipulate data using business
    8  * functions, then pass on the user to a template file.
     6 * Screen functions are the controllers of BuddyPress. They will execute when
     7 * their specific URL is caught. They will first save or manipulate data using
     8 * business functions, then pass on the user to a template file.
    99 *
    1010 * @package BuddyPress
    … …  
    1515if ( !defined( 'ABSPATH' ) ) exit;
    1616
     17/**
     18 * Catch and process the My Friends page.
     19 */
    1720function friends_screen_my_friends() {
    1821
    … …  
    2528}
    2629
     30/**
     31 * Catch and process the Requests page.
     32 */
    2733function friends_screen_requests() {
    2834    if ( bp_is_action_variable( 'accept', 0 ) && is_numeric( bp_action_variable( 1 ) ) ) {
    … …  
    6975}
    7076
     77/**
     78 * Add Friends-related settings to the Settings > Notifications page.
     79 */
    7180function friends_screen_notification_settings() {
    7281

  • trunk/bp-friends/bp-friends-template.php

    r7374 r7560  
    22
    33/**
    4  * BuddyPress Friends Template Functions
     4 * BuddyPress Friends Template Functions.
    55 *
    66 * @package BuddyPress
    … …  
    1212
    1313/**
    14  * Output the friends component slug
    15  *
    16  * @package BuddyPress
    17  * @subpackage Friends Template
    18  * @since BuddyPress (1.5)
     14 * Output the friends component slug.
     15 *
     16 * @since BuddyPress (1.5.0)
    1917 *
    2018 * @uses bp_get_friends_slug()
    … …  
    2422}
    2523    /**
    26      * Return the friends component slug
    27      *
    28      * @package BuddyPress
    29      * @subpackage Friends Template
    30      * @since BuddyPress (1.5)
     24     * Return the friends component slug.
     25     *
     26     * @since BuddyPress (1.5.0)
    3127     */
    3228    function bp_get_friends_slug() {
    … …  
    3632
    3733/**
    38  * Output the friends component root slug
    39  *
    40  * @package BuddyPress
    41  * @subpackage Friends Template
    42  * @since BuddyPress (1.5)
     34 * Output the friends component root slug.
     35 *
     36 * @since BuddyPress (1.5.0)
    4337 *
    4438 * @uses bp_get_friends_root_slug()
    … …  
    4842}
    4943    /**
    50      * Return the friends component root slug
    51      *
    52      * @package BuddyPress
    53      * @subpackage Friends Template
    54      * @since BuddyPress (1.5)
     44     * Return the friends component root slug.
     45     *
     46     * @since BuddyPress (1.5.0)
    5547     */
    5648    function bp_get_friends_root_slug() {
    … …  
    5951    }
    6052
     53/**
     54 * Output a block of random friends.
     55 *
     56 * No longer used in BuddyPress.
     57 *
     58 * @todo Deprecate
     59 */
    6160function bp_friends_random_friends() {
    6261
    … …  
    9998
    10099/**
    101  * Pull up a group of random members, and display some profile data about them
     100 * Pull up a group of random members, and display some profile data about them.
    102101 *
    103102 * This function is no longer used by BuddyPress core.
    104103 *
    105  * @package BuddyPress
    106  *
    107  * @param int $total_members The number of members to retrieve
     104 * @todo Deprecate
     105 *
     106 * @param int $total_members The number of members to retrieve.
    108107 */
    109108function bp_friends_random_members( $total_members = 5 ) {
    … …  
    164163}
    165164
     165/**
     166 * Display a Friends search form.
     167 *
     168 * No longer used in BuddyPress.
     169 *
     170 * @todo Deprecate
     171 */
    166172function bp_friend_search_form() {
    167173
    … …  
    183189}
    184190
     191/**
     192 * Output the Add Friend button in member directories.
     193 */
    185194function bp_member_add_friend_button() {
    186195    global $members_template;
    … …  
    195204add_action( 'bp_directory_members_actions', 'bp_member_add_friend_button' );
    196205
     206/**
     207 * Output the friend count for the current member in the loop.
     208 */
    197209function bp_member_total_friend_count() {
    198210    echo bp_get_member_total_friend_count();
    199211}
     212    /**
     213     * Return the friend count for the current member in the loop.
     214     *
     215     * Return value is a string of the form "x friends".
     216     *
     217     * @return string A string of the form "x friends".
     218     */
    200219    function bp_get_member_total_friend_count() {
    201220        global $members_template;
    … …  
    208227
    209228/**
    210  * bp_potential_friend_id( $user_id )
    211  *
    212  * Outputs the ID of the potential friend
    213  *
    214  * @uses bp_get_potential_friend_id()
    215  * @param int $user_id Optional
     229 * Output the ID of the current user in the friend request loop.
     230 *
     231 * @see bp_get_potential_friend_id() for a description of arguments.
     232 *
     233 * @param int $user_id See {@link bp_get_potential_friend_id()}.
    216234 */
    217235function bp_potential_friend_id( $user_id = 0 ) {
    … …  
    219237}
    220238    /**
    221      * bp_get_potential_friend_id( $user_id )
    222      *
    223      * Returns the ID of the potential friend
     239     * Return the ID of current user in the friend request loop.
    224240     *
    225241     * @global object $friends_template
    226      * @param int $user_id
    227      * @return int ID of potential friend
     242     *
     243     * @param int $user_id Optional. If provided, the function will simply
     244     *        return this value.
     245     * @return int ID of potential friend.
    228246     */
    229247    function bp_get_potential_friend_id( $user_id = 0 ) {
    … …  
    239257
    240258/**
    241  * bp_is_friend( $user_id )
    242  *
    243  * Returns - 'is_friend', 'not_friends', 'pending'
    244  *
    245  * @param int $potential_friend_id
    246  * @return string
     259 * Check whether a given user is a friend of the logged-in user.
     260 *
     261 * Returns - 'is_friend', 'not_friends', 'pending'.
     262 *
     263 * @param int $user_id ID of the potential friend. Default: the value of
     264 *        {@link bp_get_potential_friend_id()}.
     265 * @return string 'is_friend', 'not_friends', or 'pending'.
    247266 */
    248267function bp_is_friend( $user_id = 0 ) {
    … …  
    260279}
    261280
     281/**
     282 * Output the Add Friend button.
     283 *
     284 * @see bp_get_add_friend_button() for information on arguments.
     285 *
     286 * @param int $potential_friend_id See {@link bp_get_add_friend_button()}.
     287 * @param int $friend_status See {@link bp_get_add_friend_button()}.
     288 */
    262289function bp_add_friend_button( $potential_friend_id = 0, $friend_status = false ) {
    263290    echo bp_get_add_friend_button( $potential_friend_id, $friend_status );
    264291}
     292    /**
     293     * Create the Add Friend button.
     294     *
     295     * @param int $potential_friend_id ID of the user to whom the button
     296     *        applies. Default: value of {@link bp_get_potential_friend_id()}.
     297     * @param bool $friend_status Not currently used.
     298     * @return string HTML for the Add Friend button.
     299     */
    265300    function bp_get_add_friend_button( $potential_friend_id = 0, $friend_status = false ) {
    266301
    … …  
    347382    }
    348383
     384/**
     385 * Get a comma-separated list of IDs of a user's friends.
     386 *
     387 * @param int $user_id Optional. Default: the displayed user's ID, or the
     388 *        logged-in user's ID.
     389 * @return string|bool A comma-separated list of friend IDs if any are found,
     390 *         otherwise false.
     391 */
    349392function bp_get_friend_ids( $user_id = 0 ) {
    350393
    … …  
    361404
    362405/**
    363  * Get a user's friendship requests
    364  *
    365  * Note that we return a 0 if no pending requests are found. This is necessary because of the
    366  * structure of the $include parameter in bp_has_members().
    367  *
    368  * @param int $user_id Defaults to displayed user
    369  * @return mixed Returns an array of users if found, or a 0 if none are found
     406 * Get a user's friendship requests.
     407 *
     408 * Note that we return a 0 if no pending requests are found. This is necessary
     409 * because of the structure of the $include parameter in bp_has_members().
     410 *
     411 * @param int $user_id ID of the user whose requests are being retrieved.
     412 *        Defaults to displayed user.
     413 * @return array|int An array of user IDs if found, or a 0 if none are found.
    370414 */
    371415function bp_get_friendship_requests( $user_id = 0 ) {
    … …  
    389433}
    390434
     435/**
     436 * Output the ID of the friendship between the logged-in user and the current user in the loop.
     437 */
    391438function bp_friend_friendship_id() {
    392439    echo bp_get_friend_friendship_id();
    393440}
     441    /**
     442     * Return the ID of the frinedship between the logged-in user and the current user in the loop.
     443     *
     444     * @return int ID of the friendship.
     445     */
    394446    function bp_get_friend_friendship_id() {
    395447        global $members_template;
    … …  
    403455    }
    404456
     457/**
     458 * Output the URL for accepting the current friendship request in the loop.
     459 */
    405460function bp_friend_accept_request_link() {
    406461    echo bp_get_friend_accept_request_link();
    407462}
     463    /**
     464     * Return the URL for accepting the current friendship request in the loop.
     465     *
     466     * @return string accept-friendship URL.
     467     */
    408468    function bp_get_friend_accept_request_link() {
    409469        global $members_template;
    … …  
    417477    }
    418478
     479/**
     480 * Output the URL for rejecting the current friendship request in the loop.
     481 */
    419482function bp_friend_reject_request_link() {
    420483    echo bp_get_friend_reject_request_link();
    421484}
     485    /**
     486     * Return the URL for rejecting the current friendship request in the loop.
     487     *
     488     * @return string reject-friendship URL.
     489     */
    422490    function bp_get_friend_reject_request_link() {
    423491        global $members_template;
    … …  
    431499    }
    432500
     501/**
     502 * Output the total friend count for a given user.
     503 *
     504 * @param int $user_id See {@link friends_get_total_friend_count()}.
     505 */
    433506function bp_total_friend_count( $user_id = 0 ) {
    434507    echo bp_get_total_friend_count( $user_id );
    435508}
     509    /**
     510     * Return the total friend count for a given user.
     511     *
     512     * @param int $user_id See {@link friends_get_total_friend_count()}.
     513     * @return int Total friend count.
     514     */
    436515    function bp_get_total_friend_count( $user_id = 0 ) {
    437516        return apply_filters( 'bp_get_total_friend_count', friends_get_total_friend_count( $user_id ) );
    … …  
    439518    add_filter( 'bp_get_total_friend_count', 'bp_core_number_format' );
    440519
     520/**
     521 * Output the total friendship request count for a given user.
     522 *
     523 * @see bp_friend_get_total_requests_count() for description of arguments.
     524 *
     525 * @param int $user_id See {@link bp_friend_get_total_requests_count().
     526 */
    441527function bp_friend_total_requests_count( $user_id = 0 ) {
    442528    echo bp_friend_get_total_requests_count( $user_id );
    443529}
     530    /**
     531     * Return the total friendship request count for a given user.
     532     *
     533     * @param int $user_id ID of the user whose requests are being counted.
     534     *        Default: ID of the logged-in user.
     535     * @return int Friend count.
     536     */
    444537    function bp_friend_get_total_requests_count( $user_id = 0 ) {
    445538        if ( empty( $user_id ) )

  • trunk/bp-friends/bp-friends-widgets.php

    r7392 r7560  
    1414 * Register the friends widget.
    1515 *
    16  * @since 1.9.0
     16 * @since BuddyPress (1.9.0)
    1717 */
    1818function bp_friends_register_widgets() {
    … …  
    3030 * The User Friends widget class.
    3131 *
    32  * @since 1.9.0
     32 * @since BuddyPress (1.9.0)
    3333 */
    3434class BP_Core_Friends_Widget extends WP_Widget {
    … …  
    193193 * Process AJAX pagination or filtering for the Friends widget.
    194194 *
    195  * @since 1.9.0
     195 * @since BuddyPress (1.9.0)
    196196 */
    197197function bp_core_ajax_widget_friends() {
Note: See TracChangeset for help on using the changeset viewer.