Index: trunk/src/bp-groups/bp-groups-functions.php
===================================================================
--- trunk/src/bp-groups/bp-groups-functions.php	(revision 10351)
+++ trunk/src/bp-groups/bp-groups-functions.php	(revision 10373)
@@ -36,10 +36,10 @@
  *
  * @param array|string $args {
- *	Array of al arguments.
- *	@type int  $group_id        ID of the group.
- *	@type bool $load_users      No longer used.
- *	@type bool $populate_extras Whether to fetch membership data and other
- *	                            extra information about the group.
- *                              Default: false.
+ *     Array of al arguments.
+ *     @type int  $group_id        ID of the group.
+ *     @type bool $load_users      No longer used.
+ *     @type bool $populate_extras Whether to fetch membership data and other
+ *                                 extra information about the group.
+ *                                 Default: false.
  * }
  * @return BP_Groups_Group $group The group object.
@@ -84,5 +84,5 @@
  *     @type string   $slug         The group slug.
  *     @type string   $status       The group's status. Accepts 'public', 'private' or
-                                    'hidden'. Defaults to 'public'.
+ *                                  'hidden'. Defaults to 'public'.
  *     @type int      $enable_forum Optional. Whether the group has a forum enabled.
  *                                  If the legacy forums are enabled for this group
@@ -110,5 +110,5 @@
 	extract( $args, EXTR_SKIP );
 
-	// Pass an existing group ID
+	// Pass an existing group ID.
 	if ( ! empty( $group_id ) ) {
 		$group = groups_get_group( array( 'group_id' => (int) $group_id ) );
@@ -117,16 +117,16 @@
 		$description = ! empty( $description ) ? $description : $group->description;
 
-		// Groups need at least a name
+		// Groups need at least a name.
 		if ( empty( $name ) ) {
 			return false;
 		}
 
-	// Create a new group
+	// Create a new group.
 	} else {
-		// Instantiate new group object
+		// Instantiate new group object.
 		$group = new BP_Groups_Group;
 	}
 
-	// Set creator ID
+	// Set creator ID.
 	if ( $creator_id ) {
 		$group->creator_id = (int) $creator_id;
@@ -139,10 +139,10 @@
 	}
 
-	// Validate status
+	// Validate status.
 	if ( ! groups_is_valid_status( $status ) ) {
 		return false;
 	}
 
-	// Set group name
+	// Set group name.
 	$group->name         = $name;
 	$group->description  = $description;
@@ -152,10 +152,10 @@
 	$group->date_created = $date_created;
 
-	// Save group
+	// Save group.
 	if ( ! $group->save() ) {
 		return false;
 	}
 
-	// If this is a new group, set up the creator as the first member and admin
+	// If this is a new group, set up the creator as the first member and admin.
 	if ( empty( $group_id ) ) {
 		$member                = new BP_Groups_Member;
@@ -217,5 +217,4 @@
  * @param bool   $notify_members Whether to send an email notification to group
  *                               members about changes in these details.
- *
  * @return bool True on success, false on failure.
  */
@@ -263,5 +262,4 @@
  * @param string|bool $invite_status Optional. Who is allowed to send invitations
  *                                   to the group. 'members', 'mods', or 'admins'.
- *
  * @return bool True on success, false on failure.
  */
@@ -271,5 +269,5 @@
 	$group->enable_forum = $enable_forum;
 
-	/***
+	/**
 	 * Before we potentially switch the group status, if it has been changed to public
 	 * from private and there are outstanding membership requests, auto-accept those requests.
@@ -278,5 +276,5 @@
 		groups_accept_all_pending_membership_requests( $group->id );
 
-	// Now update the status
+	// Now update the status.
 	$group->status = $status;
 
@@ -291,5 +289,5 @@
 	}
 
-	// Set the invite status
+	// Set the invite status.
 	if ( $invite_status )
 		groups_update_groupmeta( $group->id, 'invite_status', $invite_status );
@@ -315,5 +313,4 @@
  *
  * @param int $group_id ID of the group to delete.
- *
  * @return bool True on success, false on failure.
  */
@@ -329,13 +326,13 @@
 	do_action( 'groups_before_delete_group', $group_id );
 
-	// Get the group object
+	// Get the group object.
 	$group = groups_get_group( array( 'group_id' => $group_id ) );
 
-	// Bail if group cannot be deleted
+	// Bail if group cannot be deleted.
 	if ( ! $group->delete() ) {
 		return false;
 	}
 
-	// Remove all outstanding invites for this group
+	// Remove all outstanding invites for this group.
 	groups_delete_all_group_invites( $group_id );
 
@@ -356,5 +353,4 @@
  *
  * @param string $status Status to check.
- *
  * @return bool True if status is allowed, otherwise false.
  */
@@ -369,5 +365,4 @@
  *
  * @param string $slug Group slug to check.
- *
  * @return string $slug A unique and sanitized slug.
  */
@@ -395,5 +390,4 @@
  *
  * @param int $group_id The numeric ID of the group.
- *
  * @return string The group's slug.
  */
@@ -409,5 +403,4 @@
  *
  * @param string $group_slug The group's slug.
- *
  * @return int The ID.
  */
@@ -424,5 +417,4 @@
  * @param int $user_id  Optional. ID of the user. Defaults to the currently
  *                      logged-in user.
- *
  * @return bool True on success, false on failure.
  */
@@ -465,5 +457,4 @@
  * @param int $user_id  Optional. ID of the user. Defaults to the currently
  *                      logged-in user.
- *
  * @return bool True on success, false on failure.
  */
@@ -481,5 +472,5 @@
 		groups_delete_membership_request( null, $user_id, $group_id );
 
-	// User is already a member, just return true
+	// User is already a member, just return true.
 	if ( groups_is_user_member( $user_id, $group_id ) )
 		return true;
@@ -504,5 +495,5 @@
 		$group = $bp->groups->current_group;
 
-	// Record this in activity streams
+	// Record this in activity streams.
 	groups_record_activity( array(
 		'type'    => 'joined_group',
@@ -530,5 +521,4 @@
  *
  * @param int $group_id ID of the group.
- *
  * @return array Info about group admins (user_id + date_modified).
  */
@@ -541,5 +531,4 @@
  *
  * @param int $group_id ID of the group.
- *
  * @return array Info about group admins (user_id + date_modified).
  */
@@ -580,5 +569,5 @@
 function groups_get_group_members( $args = array() ) {
 
-	// Backward compatibility with old method of passing arguments
+	// Backward compatibility with old method of passing arguments.
 	if ( ! is_array( $args ) || func_num_args() > 1 ) {
 		_deprecated_argument( __METHOD__, '2.0.0', sprintf( __( 'Arguments passed to %1$s should be in an associative array. See the inline documentation at %2$s for more details.', 'buddypress' ), __METHOD__, __FILE__ ) );
@@ -612,5 +601,5 @@
 	// For legacy users. Use of BP_Groups_Member::get_all_for_group()
 	// is deprecated. func_get_args() can't be passed to a function in PHP
-	// 5.2.x, so we create a variable
+	// 5.2.x, so we create a variable.
 	$func_args = func_get_args();
 	if ( apply_filters( 'bp_use_legacy_group_member_query', false, __FUNCTION__, $func_args ) ) {
@@ -618,6 +607,6 @@
 	} else {
 
-		// exclude_admins_mods and exclude_banned are legacy arguments.
-		// Convert to group_role
+		// Both exclude_admins_mods and exclude_banned are legacy arguments.
+		// Convert to group_role.
 		if ( empty( $r['group_role'] ) ) {
 			$r['group_role'] = array( 'member' );
@@ -633,5 +622,5 @@
 		}
 
-		// Perform the group member query (extends BP_User_Query)
+		// Perform the group member query (extends BP_User_Query).
 		$members = new BP_Group_Member_Query( array(
 			'group_id'       => $r['group_id'],
@@ -644,5 +633,5 @@
 		) );
 
-		// Structure the return value as expected by the template functions
+		// Structure the return value as expected by the template functions.
 		$retval = array(
 			'members' => array_values( $members->results ),
@@ -658,5 +647,4 @@
  *
  * @param int $group_id Group ID.
- *
  * @return int Count of confirmed members for the group.
  */
@@ -682,17 +670,17 @@
 
 	$defaults = array(
-		'type'              => false,    // active, newest, alphabetical, random, popular, most-forum-topics or most-forum-posts
-		'order'             => 'DESC',   // 'ASC' or 'DESC'
-		'orderby'           => 'date_created', // date_created, last_activity, total_member_count, name, random
-		'user_id'           => false,    // Pass a user_id to limit to only groups that this user is a member of
-		'include'           => false,    // Only include these specific groups (group_ids)
-		'exclude'           => false,    // Do not include these specific groups (group_ids)
-		'search_terms'      => false,    // Limit to groups that match these search terms
-		'meta_query'        => false,    // Filter by groupmeta. See WP_Meta_Query for syntax
-		'show_hidden'       => false,    // Show hidden groups to non-admins
-		'per_page'          => 20,       // The number of results to return per page
-		'page'              => 1,        // The page to return if limiting per page
-		'populate_extras'   => true,     // Fetch meta such as is_banned and is_member
-		'update_meta_cache' => true,   // Pre-fetch groupmeta for queried groups
+		'type'              => false,          // Active, newest, alphabetical, random, popular, most-forum-topics or most-forum-posts.
+		'order'             => 'DESC',         // 'ASC' or 'DESC'
+		'orderby'           => 'date_created', // date_created, last_activity, total_member_count, name, random.
+		'user_id'           => false,          // Pass a user_id to limit to only groups that this user is a member of.
+		'include'           => false,          // Only include these specific groups (group_ids).
+		'exclude'           => false,          // Do not include these specific groups (group_ids).
+		'search_terms'      => false,          // Limit to groups that match these search terms.
+		'meta_query'        => false,          // Filter by groupmeta. See WP_Meta_Query for syntax.
+		'show_hidden'       => false,          // Show hidden groups to non-admins.
+		'per_page'          => 20,             // The number of results to return per page.
+		'page'              => 1,              // The page to return if limiting per page.
+		'populate_extras'   => true,           // Fetch meta such as is_banned and is_member.
+		'update_meta_cache' => true,           // Pre-fetch groupmeta for queried groups.
 	);
 
@@ -769,5 +757,4 @@
  *
  * @param int $user_id Optional. Default: ID of the displayed user.
- *
  * @return int Group count.
  */
@@ -816,6 +803,5 @@
  * Generate the avatar upload directory path for a given group.
  *
- * @param int $group_id Optional. ID of the group. Default: ID of the
- *                      current group.
+ * @param int $group_id Optional. ID of the group. Default: ID of the current group.
  * @return string
  */
@@ -857,5 +843,4 @@
  * @param int $user_id ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool
  */
@@ -869,5 +854,4 @@
  * @param int $user_id ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool
  */
@@ -881,5 +865,4 @@
  * @param int $user_id ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool
  */
@@ -899,5 +882,4 @@
  * @param int $user_id ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool
  */
@@ -947,5 +929,5 @@
 		return false;
 
-	// Record this in activity streams
+	// Record this in activity streams.
 	$activity_action  = sprintf( __( '%1$s posted an update in the group %2$s', 'buddypress'), bp_core_get_userlink( $user_id ), '<a href="' . bp_get_group_permalink( $bp->groups->current_group ) . '">' . esc_attr( $bp->groups->current_group->name ) . '</a>' );
 	$activity_content = $content;
@@ -1000,8 +982,8 @@
  *
  * @param int               $user_id ID of the inviting user.
- * @param int|bool          $limit Limit to restrict to.
- * @param int|bool          $page
- * @param string|array|bool $exclude
- *
+ * @param int|bool          $limit   Limit to restrict to.
+ * @param int|bool          $page    Optional. Page offset of results to return.
+ * @param string|array|bool $exclude Array of comma-separated list of group IDs
+ *                                   to exclude from results.
  * @return array $value IDs of users who have been invited to the group by the
  *                      user but have not yet accepted.
@@ -1021,5 +1003,4 @@
  *
  * @param int $user_id The user ID.
- *
  * @return int
  */
@@ -1064,9 +1045,9 @@
 		return false;
 
-	// if the user has already requested membership, accept the request
+	// If the user has already requested membership, accept the request.
 	if ( $membership_id = groups_check_for_membership_request( $user_id, $group_id ) ) {
 		groups_accept_membership_request( $membership_id, $user_id, $group_id );
 
-	// Otherwise, create a new invitation
+	// Otherwise, create a new invitation.
 	} elseif ( ! groups_is_user_member( $user_id, $group_id ) && ! groups_check_user_has_invite( $user_id, $group_id, 'all' ) ) {
 		$invite                = new BP_Groups_Member;
@@ -1100,5 +1081,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1128,5 +1108,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool True when the user is a member of the group, otherwise false.
  */
@@ -1134,5 +1113,5 @@
 
 	// If the user is already a member (because BP at one point allowed two invitations to
-	// slip through), delete all existing invitations/requests and return true
+	// slip through), delete all existing invitations/requests and return true.
 	if ( groups_is_user_member( $user_id, $group_id ) ) {
 		if ( groups_check_user_has_invite( $user_id, $group_id ) ) {
@@ -1154,10 +1133,10 @@
 	}
 
-	// Remove request to join
+	// Remove request to join.
 	if ( $member->check_for_membership_request( $user_id, $group_id ) ) {
 		$member->delete_request( $user_id, $group_id );
 	}
 
-	// Modify group meta
+	// Modify group meta.
 	groups_update_groupmeta( $group_id, 'last_activity', bp_core_current_time() );
 
@@ -1180,5 +1159,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1205,5 +1183,4 @@
  * @param int $user_id  ID of the invited user.
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1243,5 +1220,5 @@
 		$member = new BP_Groups_Member( $invited_users[$i], $group_id );
 
-		// Send the actual invite
+		// Send the actual invite.
 		groups_notification_group_invites( $group, $member, $user_id );
 
@@ -1268,5 +1245,4 @@
  * @param int $user_id  ID of the inviting user.
  * @param int $group_id ID of the group.
- *
  * @return array $value IDs of users who have been invited to the group by the
  *                      user but have not yet accepted.
@@ -1287,5 +1263,4 @@
  * @param string $type     Optional. Use 'sent' to check for sent invites,
  *                         'all' to check for all. Default: 'sent'.
- *
  * @return bool True if an invitation is found, otherwise false.
  */
@@ -1298,5 +1273,4 @@
  *
  * @param int $group_id ID of the group whose invitations are being deleted.
- *
  * @return int|null Number of rows records deleted on success, null on failure.
  */
@@ -1313,5 +1287,4 @@
  * @param int    $group_id ID of the group.
  * @param string $status   The new status. 'mod' or 'admin'.
- *
  * @return bool True on success, false on failure.
  */
@@ -1345,5 +1318,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1373,5 +1345,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1401,5 +1372,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1431,5 +1401,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1462,18 +1431,17 @@
  * @param int $requesting_user_id ID of the user requesting membership.
  * @param int $group_id           ID of the group.
- *
  * @return bool True on success, false on failure.
  */
 function groups_send_membership_request( $requesting_user_id, $group_id ) {
 
-	// Prevent duplicate requests
+	// Prevent duplicate requests.
 	if ( groups_check_for_membership_request( $requesting_user_id, $group_id ) )
 		return false;
 
-	// Check if the user is already a member or is banned
+	// Check if the user is already a member or is banned.
 	if ( groups_is_user_member( $requesting_user_id, $group_id ) || groups_is_user_banned( $requesting_user_id, $group_id ) )
 		return false;
 
-	// Check if the user is already invited - if so, simply accept invite
+	// Check if the user is already invited - if so, simply accept invite.
 	if ( groups_check_user_has_invite( $requesting_user_id, $group_id ) ) {
 		groups_accept_invite( $requesting_user_id, $group_id );
@@ -1494,5 +1462,5 @@
 		$admins = groups_get_group_admins( $group_id );
 
-		// Saved okay, now send the email notification
+		// Saved okay, now send the email notification.
 		for ( $i = 0, $count = count( $admins ); $i < $count; ++$i )
 			groups_notification_new_membership_request( $requesting_user_id, $admins[$i]->user_id, $group_id, $requesting_user->id );
@@ -1526,5 +1494,4 @@
  *                           requested. Provide this value along with $user_id to
  *                           override $membership_id.
- *
  * @return bool True on success, false on failure.
  */
@@ -1572,5 +1539,4 @@
  *                           requested. Provide this value along with $user_id to
  *                           override $membership_id.
- *
  * @return bool True on success, false on failure.
  */
@@ -1604,5 +1570,4 @@
  *                           requested. Provide this value along with $user_id to
  *                           override $membership_id.
- *
  * @return bool True on success, false on failure.
  */
@@ -1624,5 +1589,4 @@
  * @param int $user_id  ID of the user.
  * @param int $group_id ID of the group.
- *
  * @return int|null ID of the membership if found, otherwise false.
  */
@@ -1635,5 +1599,4 @@
  *
  * @param int $group_id ID of the group.
- *
  * @return bool True on success, false on failure.
  */
@@ -1672,5 +1635,4 @@
  *                                metadata entries for the specified group.
  *                                Default: false.
- *
  * @return bool True on success, false on failure.
  */
@@ -1678,9 +1640,9 @@
 	global $wpdb;
 
-	// Legacy - if no meta_key is passed, delete all for the item
+	// Legacy - if no meta_key is passed, delete all for the item.
 	if ( empty( $meta_key ) ) {
 		$keys = $wpdb->get_col( $wpdb->prepare( "SELECT meta_key FROM {$wpdb->groupmeta} WHERE group_id = %d", $group_id ) );
 
-		// With no meta_key, ignore $delete_all
+		// With no meta_key, ignore $delete_all.
 		$delete_all = false;
 	} else {
@@ -1708,5 +1670,4 @@
  *                         specified meta_key. This parameter has no effect if
  *                         meta_key is empty.
- *
  * @return mixed Metadata value.
  */
@@ -1728,5 +1689,4 @@
  *                           metadata entries with the specified value.
  *                           Otherwise, update all entries.
- *
  * @return bool|int $retval Returns false on failure. On successful update of existing
  *                          metadata, returns true. On successful creation of new metadata,
@@ -1753,5 +1713,4 @@
  *                           has a value for the key, no change will be made.
  *                           Default: false.
- *
  * @return int|bool The meta ID on successful update, false on failure.
  */
