<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[BuddyPress][7558] trunk/bp-friends: Improve inline docs in bp-friends component.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://buddypress.trac.wordpress.org/changeset/7558">7558</a></dd>
<dt>Author</dt> <dd>boonebgorges</dd>
<dt>Date</dt> <dd>2013-11-11 00:52:44 +0000 (Mon, 11 Nov 2013)</dd>
</dl>
<h3>Log Message</h3>
<pre>Improve inline docs in bp-friends component. See <a href="http://buddypress.trac.wordpress.org/ticket/5022">#5022</a></pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkbpfriendsbpfriendsfiltersphp">trunk/bp-friends/bp-friends-filters.php</a></li>
<li><a href="#trunkbpfriendsbpfriendsfunctionsphp">trunk/bp-friends/bp-friends-functions.php</a></li>
<li><a href="#trunkbpfriendsbpfriendsloaderphp">trunk/bp-friends/bp-friends-loader.php</a></li>
<li><a href="#trunkbpfriendsbpfriendsnotificationsphp">trunk/bp-friends/bp-friends-notifications.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkbpfriendsbpfriendsfiltersphp"></a>
<div class="modfile"><h4>Modified: trunk/bp-friends/bp-friends-filters.php (7557 => 7558)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/bp-friends/bp-friends-filters.php 2013-11-10 23:05:35 UTC (rev 7557)
+++ trunk/bp-friends/bp-friends-filters.php 2013-11-11 00:52:44 UTC (rev 7558)
</span><span class="lines">@@ -8,14 +8,16 @@
</span><span class="cx"> */
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Filter BP_User_Query::populate_extras to override each queried users fullname
</del><ins>+ * Filter BP_User_Query::populate_extras to override each queried users fullname.
</ins><span class="cx"> *
</span><del>- * @since BuddyPress (1.7)
</del><ins>+ * @since BuddyPress (1.7.0)
</ins><span class="cx"> *
</span><del>- * @global BuddyPress $bp
- * @global WPDB $wpdb
- * @param BP_User_Query $user_query
- * @param string $user_ids_sql
</del><ins>+ * @global BuddyPress $bp Global BuddyPress settings.
+ * @global WPDB $wpdb WordPress database access object.
+ *
+ * @param BP_User_Query $user_query The BP_User_Query object.
+ * @param string $user_ids_sql Comma-separated list of user IDs to fetch extra
+ * data for, as determined by BP_User_Query.
</ins><span class="cx"> */
</span><span class="cx"> function bp_friends_filter_user_query_populate_extras( BP_User_Query $user_query, $user_ids_sql ) {
</span><span class="cx"> global $bp, $wpdb;
</span></span></pre></div>
<a id="trunkbpfriendsbpfriendsfunctionsphp"></a>
<div class="modfile"><h4>Modified: trunk/bp-friends/bp-friends-functions.php (7557 => 7558)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/bp-friends/bp-friends-functions.php 2013-11-10 23:05:35 UTC (rev 7557)
+++ trunk/bp-friends/bp-friends-functions.php 2013-11-11 00:52:44 UTC (rev 7558)
</span><span class="lines">@@ -15,6 +15,19 @@
</span><span class="cx"> // Exit if accessed directly
</span><span class="cx"> if ( !defined( 'ABSPATH' ) ) exit;
</span><span class="cx">
</span><ins>+/**
+ * Create a new friendship.
+ *
+ * @param int $initiator_userid ID of the "initiator" user (the user who is
+ * sending the friendship request).
+ * @param int $friend_userid ID of the "friend" user (the user whose friendship
+ * is being requested).
+ * @param bool $force_accept Optional. Whether to force acceptance. When false,
+ * running friends_add_friend() will result in a friendship request.
+ * When true, running friends_add_friend() will result in an accepted
+ * friendship, with no notifications being sent. Default: false.
+ * @return bool True on success, false on failure.
+ */
</ins><span class="cx"> function friends_add_friend( $initiator_userid, $friend_userid, $force_accept = false ) {
</span><span class="cx"> global $bp;
</span><span class="cx">
</span><span class="lines">@@ -55,6 +68,15 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Remove a friendship.
+ *
+ * Will also delete the related "friendship_accepted" activity item.
+ *
+ * @param int $initiator_userid ID of the friendship initiator.
+ * @param int $friend_userid ID of the friend user.
+ * @return bool True on success, false on failure.
+ */
</ins><span class="cx"> function friends_remove_friend( $initiator_userid, $friend_userid ) {
</span><span class="cx">
</span><span class="cx"> $friendship_id = BP_Friends_Friendship::get_friendship_id( $initiator_userid, $friend_userid );
</span><span class="lines">@@ -80,6 +102,14 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Mark a friendship request as accepted.
+ *
+ * Also initiates a "friendship_accepted" activity item.
+ *
+ * @param int $friendship_id ID of the pending friendship object.
+ * @return bool True on success, false on failure.
+ */
</ins><span class="cx"> function friends_accept_friendship( $friendship_id ) {
</span><span class="cx"> global $bp;
</span><span class="cx">
</span><span class="lines">@@ -127,6 +157,12 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Mark a friendship request as rejected.
+ *
+ * @param int $friendship_id ID of the pending friendship object.
+ * @return bool True on success, false on failure.
+ */
</ins><span class="cx"> function friends_reject_friendship( $friendship_id ) {
</span><span class="cx"> global $bp;
</span><span class="cx">
</span><span class="lines">@@ -144,6 +180,14 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Withdraw a friendship request.
+ *
+ * @param int $initiator_userid ID of the friendship initiator - this is the
+ * user who requested the friendship, and is doing the withdrawing.
+ * @param int $friend_userid ID of the requested friend.
+ * @return bool True on success, false on failure.
+ */
</ins><span class="cx"> function friends_withdraw_friendship( $initiator_userid, $friend_userid ) {
</span><span class="cx"> global $bp;
</span><span class="cx">
</span><span class="lines">@@ -161,6 +205,13 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Check whether two users are friends.
+ *
+ * @param int $user_id ID of the first user.
+ * @param int $possible_friend_id ID of the other user.
+ * @return bool Returns true if the two users are friends, otherwise false.
+ */
</ins><span class="cx"> function friends_check_friendship( $user_id, $possible_friend_id ) {
</span><span class="cx">
</span><span class="cx"> if ( 'is_friend' == BP_Friends_Friendship::check_is_friend( $user_id, $possible_friend_id ) )
</span><span class="lines">@@ -169,11 +220,25 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><del>-// Returns - 'is_friend', 'not_friends', 'pending'
</del><ins>+/**
+ * Get the friendship status of two friends.
+ *
+ * Will return 'is_friends', 'not_friends', or 'pending'.
+ *
+ * @param int $user_id ID of the first user.
+ * @param int $possible_friend_id ID of the other user.
+ * @return string Friend status of the two users.
+ */
</ins><span class="cx"> function friends_check_friendship_status( $user_id, $possible_friend_id ) {
</span><span class="cx"> return BP_Friends_Friendship::check_is_friend( $user_id, $possible_friend_id );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get the friend count of a given user.
+ *
+ * @param int $user_id ID of the user whose friends are being counted.
+ * @return int Friend count of the user.
+ */
</ins><span class="cx"> function friends_get_total_friend_count( $user_id = 0 ) {
</span><span class="cx"> if ( empty( $user_id ) )
</span><span class="cx"> $user_id = ( bp_displayed_user_id() ) ? bp_displayed_user_id() : bp_loggedin_user_id();
</span><span class="lines">@@ -185,6 +250,12 @@
</span><span class="cx"> return apply_filters( 'friends_get_total_friend_count', $count );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Check whether a given user has any friends.
+ *
+ * @param int $user_id ID of the user whose friends are being checked.
+ * @return bool True if the user has friends, otherwise false.
+ */
</ins><span class="cx"> function friends_check_user_has_friends( $user_id ) {
</span><span class="cx"> $friend_count = friends_get_total_friend_count( $user_id );
</span><span class="cx">
</span><span class="lines">@@ -197,34 +268,124 @@
</span><span class="cx"> return true;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get the ID of two users' friendship, if it exists.
+ *
+ * @param int $initiator_user_id ID of the first user.
+ * @param int $friend_user_id ID of the second user.
+ * @return int|bool ID of the friendship if found, otherwise false.
+ */
</ins><span class="cx"> function friends_get_friendship_id( $initiator_user_id, $friend_user_id ) {
</span><span class="cx"> return BP_Friends_Friendship::get_friendship_id( $initiator_user_id, $friend_user_id );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get the IDs of a given user's friends.
+ *
+ * @param int $user_id ID of the user whose friends are being retreived.
+ * @param bool $friend_requests_only Optional. Whether to fetch unaccepted
+ * requests only. Default: false.
+ * @param bool $assoc_arr Optional. True to receive an array of arrays keyed as
+ * 'user_id' => $user_id; false to get a one-dimensional array of user
+ * IDs. Default: false.
+ */
</ins><span class="cx"> function friends_get_friend_user_ids( $user_id, $friend_requests_only = false, $assoc_arr = false ) {
</span><span class="cx"> return BP_Friends_Friendship::get_friend_user_ids( $user_id, $friend_requests_only, $assoc_arr );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Search the friends of a user by a search string.
+ *
+ * @param string $filter The search string, matched against xprofile fields (if
+ * available), or usermeta 'nickname' field.
+ * @param int $user_id ID of the user whose friends are being searched.
+ * @param int $limit Optional. Max number of friends to return.
+ * @param int $page Optional. The page of results to return. Default: null (no
+ * pagination - return all results).
+ * @return array|bool On success, an array: {
+ * @type array $friends IDs of friends returned by the query.
+ * @type int $count Total number of friends (disregarding
+ * pagination) who match the search.
+ * }. Returns false on failure.
+ */
</ins><span class="cx"> function friends_search_friends( $search_terms, $user_id, $pag_num = 10, $pag_page = 1 ) {
</span><span class="cx"> return BP_Friends_Friendship::search_friends( $search_terms, $user_id, $pag_num, $pag_page );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get a list of IDs of users who have requested friendship of a given user.
+ *
+ * @param int $user_id The ID of the user who has received the friendship
+ * requests.
+ * @return array|bool An array of user IDs, or false if none are found.
+ */
</ins><span class="cx"> function friends_get_friendship_request_user_ids( $user_id ) {
</span><span class="cx"> return BP_Friends_Friendship::get_friendship_request_user_ids( $user_id );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get a user's most recently active friends.
+ *
+ * @see BP_Core_User::get_users() for a description of return value.
+ *
+ * @param int $user_id ID of the user whose friends are being retreived.
+ * @param int $per_page Optional. Number of results to return per page.
+ * Default: 0 (no pagination; show all results).
+ * @param int $page Optional. Number of the page of results to return.
+ * Default: 0 (no pagination; show all results).
+ * @param string $filter Optional. Limit results to those matching a search
+ * string.
+ * @return array See {@link BP_Core_User::get_users()}.
+ */
</ins><span class="cx"> function friends_get_recently_active( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
</span><span class="cx"> return apply_filters( 'friends_get_recently_active', BP_Core_User::get_users( 'active', $per_page, $page, $user_id, $filter ) );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get a user's friends, in alphabetical order.
+ *
+ * @see BP_Core_User::get_users() for a description of return value.
+ *
+ * @param int $user_id ID of the user whose friends are being retreived.
+ * @param int $per_page Optional. Number of results to return per page.
+ * Default: 0 (no pagination; show all results).
+ * @param int $page Optional. Number of the page of results to return.
+ * Default: 0 (no pagination; show all results).
+ * @param string $filter Optional. Limit results to those matching a search
+ * string.
+ * @return array See {@link BP_Core_User::get_users()}.
+ */
</ins><span class="cx"> function friends_get_alphabetically( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
</span><span class="cx"> return apply_filters( 'friends_get_alphabetically', BP_Core_User::get_users( 'alphabetical', $per_page, $page, $user_id, $filter ) );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get a user's friends, in the order in which they joined the site.
+ *
+ * @see BP_Core_User::get_users() for a description of return value.
+ *
+ * @param int $user_id ID of the user whose friends are being retreived.
+ * @param int $per_page Optional. Number of results to return per page.
+ * Default: 0 (no pagination; show all results).
+ * @param int $page Optional. Number of the page of results to return.
+ * Default: 0 (no pagination; show all results).
+ * @param string $filter Optional. Limit results to those matching a search
+ * string.
+ * @return array See {@link BP_Core_User::get_users()}.
+ */
</ins><span class="cx"> function friends_get_newest( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
</span><span class="cx"> return apply_filters( 'friends_get_newest', BP_Core_User::get_users( 'newest', $per_page, $page, $user_id, $filter ) );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get the last active date of many users at once.
+ *
+ * @see BP_Friends_Friendship::get_bulk_last_active() for a description of
+ * arguments and return value.
+ *
+ * @param array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
+ * @return array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
+ */
</ins><span class="cx"> function friends_get_bulk_last_active( $friend_ids ) {
</span><span class="cx"> return BP_Friends_Friendship::get_bulk_last_active( $friend_ids );
</span><span class="cx"> }
</span><span class="lines">@@ -235,10 +396,12 @@
</span><span class="cx"> * Excludes friends that are already in the group, and banned friends if the
</span><span class="cx"> * user is not a group admin.
</span><span class="cx"> *
</span><del>- * @since BuddyPress (1.0)
- * @param int $user_id User ID whose friends to see can be invited
- * @param int $group_id Group to check possible invitations against
- * @return mixed False if no friends, array of users if friends
</del><ins>+ * @since BuddyPress (1.0.0)
+ *
+ * @param int $user_id User ID whose friends to see can be invited. Default:
+ * ID of the logged-in user.
+ * @param int $group_id Group to check possible invitations against.
+ * @return mixed False if no friends, array of users if friends.
</ins><span class="cx"> */
</span><span class="cx"> function friends_get_friends_invite_list( $user_id = 0, $group_id = 0 ) {
</span><span class="cx">
</span><span class="lines">@@ -303,14 +466,45 @@
</span><span class="cx"> return apply_filters( 'bp_friends_get_invite_list', $friends, $user_id, $group_id );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get a count of a user's friends who can be invited to a given group.
+ *
+ * Users can invite any of their friends except:
+ *
+ * - users who are already in the group
+ * - users who have a pending invite to the group
+ * - users who have been banned from the group
+ *
+ * @param int $user_id ID of the user whose friends are being counted.
+ * @param int $group_id ID of the group friends are being invited to.
+ * @return int $invitable_count Eligible friend count.
+ */
</ins><span class="cx"> function friends_count_invitable_friends( $user_id, $group_id ) {
</span><span class="cx"> return BP_Friends_Friendship::get_invitable_friend_count( $user_id, $group_id );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Get a total friend count for a given user.
+ *
+ * @param int $user_id Optional. ID of the user whose friendships you are
+ * counting. Default: displayed user (if any), otherwise logged-in user.
+ * @return int Friend count for the user.
+ */
</ins><span class="cx"> function friends_get_friend_count_for_user( $user_id ) {
</span><span class="cx"> return BP_Friends_Friendship::total_friend_count( $user_id );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Return a list of a user's friends, filtered by a search term.
+ *
+ * @param string $search_terms Search term to filter on.
+ * @param int $user_id ID of the user whose friends are being searched.
+ * @param int $pag_num Number of results to return per page. Default: 0 (no
+ * pagination - show all results).
+ * @param int $pag_num Number of the page being requested. Default: 0 (no
+ * pagination - show all results).
+ * @return array Array of BP_Core_User objects corresponding to friends.
+ */
</ins><span class="cx"> function friends_search_users( $search_terms, $user_id, $pag_num = 0, $pag_page = 0 ) {
</span><span class="cx">
</span><span class="cx"> $user_ids = BP_Friends_Friendship::search_users( $search_terms, $user_id, $pag_num, $pag_page );
</span><span class="lines">@@ -325,11 +519,30 @@
</span><span class="cx"> return array( 'users' => $users, 'count' => BP_Friends_Friendship::search_users_count( $search_terms ) );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Has a friendship been confirmed (accepted)?
+ *
+ * @param int $friendship_id The ID of the friendship being checked.
+ * @return bool True if the friendship is confirmed, otherwise false.
+ */
</ins><span class="cx"> function friends_is_friendship_confirmed( $friendship_id ) {
</span><span class="cx"> $friendship = new BP_Friends_Friendship( $friendship_id );
</span><span class="cx"> return $friendship->is_confirmed;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Update user friend counts.
+ *
+ * Friend counts are cached in usermeta for performance reasons. After a
+ * friendship event (acceptance, deletion), call this function to regenerate
+ * the cached values.
+ *
+ * @param int $initiator_user_id ID of the first user.
+ * @param int $friend_user_id ID of the second user.
+ * @param string $status Optional. The friendship event that's been triggered.
+ * 'add' will ++ each user's friend counts, while any other string
+ * will --.
+ */
</ins><span class="cx"> function friends_update_friend_totals( $initiator_user_id, $friend_user_id, $status = 'add' ) {
</span><span class="cx">
</span><span class="cx"> if ( 'add' == $status ) {
</span><span class="lines">@@ -341,6 +554,17 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Remove all friends-related data concerning a given user.
+ *
+ * Removes the following:
+ *
+ * - Friendships of which the user is a member
+ * - Cached friend count for the user
+ * - Notifications of friendship requests sent by the user
+ *
+ * @param int $user_id ID of the user whose friend data is being removed.
+ */
</ins><span class="cx"> function friends_remove_data( $user_id ) {
</span><span class="cx"> global $bp;
</span><span class="cx">
</span></span></pre></div>
<a id="trunkbpfriendsbpfriendsloaderphp"></a>
<div class="modfile"><h4>Modified: trunk/bp-friends/bp-friends-loader.php (7557 => 7558)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/bp-friends/bp-friends-loader.php 2013-11-10 23:05:35 UTC (rev 7557)
+++ trunk/bp-friends/bp-friends-loader.php 2013-11-11 00:52:44 UTC (rev 7558)
</span><span class="lines">@@ -2,10 +2,10 @@
</span><span class="cx"> /**
</span><span class="cx"> * BuddyPress Friends Streams Loader
</span><span class="cx"> *
</span><del>- * The friends component is for users to create relationships with each other
</del><ins>+ * The friends component is for users to create relationships with each other.
</ins><span class="cx"> *
</span><span class="cx"> * @package BuddyPress
</span><del>- * @subpackage Friends Core
</del><ins>+ * @subpackage Friends
</ins><span class="cx"> */
</span><span class="cx">
</span><span class="cx"> // Exit if accessed directly
</span><span class="lines">@@ -14,9 +14,9 @@
</span><span class="cx"> class BP_Friends_Component extends BP_Component {
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Start the friends component creation process
</del><ins>+ * Start the friends component creation process.
</ins><span class="cx"> *
</span><del>- * @since BuddyPress (1.5)
</del><ins>+ * @since BuddyPress (1.5.0)
</ins><span class="cx"> */
</span><span class="cx"> function __construct() {
</span><span class="cx"> parent::start(
</span><span class="lines">@@ -30,7 +30,11 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Include files
</del><ins>+ * Include bp-friends files.
+ *
+ * @see BP_Component::includes() for description of parameters.
+ *
+ * @param array $includes See {@link BP_Component::includes()}.
</ins><span class="cx"> */
</span><span class="cx"> public function includes( $includes = array() ) {
</span><span class="cx"> $includes = array(
</span><span class="lines">@@ -49,12 +53,16 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Setup globals
</del><ins>+ * Set up bp-friends global settings.
</ins><span class="cx"> *
</span><span class="cx"> * The BP_FRIENDS_SLUG constant is deprecated, and only used here for
</span><span class="cx"> * backwards compatibility.
</span><span class="cx"> *
</span><del>- * @since BuddyPress (1.5)
</del><ins>+ * @since BuddyPress (1.5.0)
+ *
+ * @see BP_Component::setup_globals() for description of parameters.
+ *
+ * @param array $args See {@link BP_Component::setup_globals()}.
</ins><span class="cx"> */
</span><span class="cx"> public function setup_globals( $args = array() ) {
</span><span class="cx"> $bp = buddypress();
</span><span class="lines">@@ -89,7 +97,16 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Setup BuddyBar navigation
</del><ins>+ * Set up component navigation.
+ *
+ * @since BuddyPress (1.5.0)
+ *
+ * @see BP_Component::setup_nav() for a description of arguments.
+ *
+ * @param array $main_nav Optional. See BP_Component::setup_nav() for
+ * description.
+ * @param array $sub_nav Optional. See BP_Component::setup_nav() for
+ * description.
</ins><span class="cx"> */
</span><span class="cx"> public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
</span><span class="cx"> $bp = buddypress();
</span><span class="lines">@@ -140,7 +157,14 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Set up the Toolbar
</del><ins>+ * Set up bp-friends integration with the WordPress admin bar.
+ *
+ * @since BuddyPress (1.5.0)
+ *
+ * @see BP_Component::setup_admin_bar() for a description of arguments.
+ *
+ * @param array $wp_admin_nav See BP_Component::setup_admin_bar()
+ * for description.
</ins><span class="cx"> */
</span><span class="cx"> public function setup_admin_bar( $wp_admin_nav = array() ) {
</span><span class="cx"> $bp = buddypress();
</span><span class="lines">@@ -191,7 +215,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sets up the title for pages and <title>
</del><ins>+ * Set up the title for pages and <title>.
</ins><span class="cx"> */
</span><span class="cx"> function setup_title() {
</span><span class="cx"> $bp = buddypress();
</span><span class="lines">@@ -214,6 +238,9 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Set up the bp-forums component.
+ */
</ins><span class="cx"> function bp_setup_friends() {
</span><span class="cx"> buddypress()->friends = new BP_Friends_Component();
</span><span class="cx"> }
</span></span></pre></div>
<a id="trunkbpfriendsbpfriendsnotificationsphp"></a>
<div class="modfile"><h4>Modified: trunk/bp-friends/bp-friends-notifications.php (7557 => 7558)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/bp-friends/bp-friends-notifications.php 2013-11-10 23:05:35 UTC (rev 7557)
+++ trunk/bp-friends/bp-friends-notifications.php 2013-11-11 00:52:44 UTC (rev 7558)
</span><span class="lines">@@ -13,6 +13,16 @@
</span><span class="cx"> // Exit if accessed directly
</span><span class="cx"> if ( !defined( 'ABSPATH' ) ) exit;
</span><span class="cx">
</span><ins>+/**
+ * Send notifications related to a new friendship request.
+ *
+ * When a friendship is requested, an email and a BP notification are sent to
+ * the user of whom friendship has been requested ($friend_id).
+ *
+ * @param int $friendship_id ID of the friendship object.
+ * @param int $initiator_id ID of the user who initiated the request.
+ * @param int $friend_id ID of the request recipient.
+ */
</ins><span class="cx"> function friends_notification_new_request( $friendship_id, $initiator_id, $friend_id ) {
</span><span class="cx">
</span><span class="cx"> $initiator_name = bp_core_get_user_displayname( $initiator_id );
</span><span class="lines">@@ -54,6 +64,16 @@
</span><span class="cx"> do_action( 'bp_friends_sent_request_email', $friend_id, $subject, $message, $friendship_id, $initiator_id );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Send notifications related to the acceptance of a friendship request.
+ *
+ * When a friendship request is accepted, an email and a BP notification are
+ * sent to the user who requested the friendship ($initiator_id).
+ *
+ * @param int $friendship_id ID of the friendship object.
+ * @param int $initiator_id ID of the user who initiated the request.
+ * @param int $friend_id ID of the request recipient.
+ */
</ins><span class="cx"> function friends_notification_accepted_request( $friendship_id, $initiator_id, $friend_id ) {
</span><span class="cx">
</span><span class="cx"> $friend_name = bp_core_get_user_displayname( $friend_id );
</span></span></pre>
</div>
</div>
</body>
</html>