Skip to:
Content

BuddyPress.org

Changeset 9027


Ignore:
Timestamp:
09/17/2014 01:49:22 AM (10 years ago)
Author:
boonebgorges
Message:

Improved inline documentation in bp-groups

See #5022

Location:
trunk/src/bp-groups
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/bp-groups/bp-groups-classes.php

    r9026 r9027  
    632632     *           information (such as member count) about groups. Default:
    633633     *           true.
    634      *     @type array|string Optional. Array or comma-separated list of
    635      *           group IDs. Results will exclude the listed groups.
     634     *     @type array|string $exclude Optional. Array or comma-separated
     635     *           list of group IDs. Results will exclude the listed groups.
    636636     *           Default: false.
     637     *     @type bool $update_meta_cache Whether to pre-fetch groupmeta for
     638     *           the returned groups. Default: true.
    637639     *     @type bool $show_hidden Whether to include hidden groups in
    638640     *           results. Default: false.

  • trunk/src/bp-groups/bp-groups-functions.php

    r8662 r9027  
    1717
    1818/**
    19  * Checks $bp pages global and looks for directory page
    20  *
    21  * @since BuddyPress (1.5)
     19 * Check whether there is a Groups directory page in the $bp global.
     20 *
     21 * @since BuddyPress (1.5.0)
    2222 *
    2323 * @global BuddyPress $bp The one true BuddyPress instance
    … …  
    3131
    3232/**
    33  * Pulls up the database object corresponding to a group
     33 * Fetch a single group object.
    3434 *
    3535 * When calling up a group object, you should always use this function instead
    … …  
    3737 * support and pass through the groups_get_group filter.
    3838 *
    39  * @param string $args The load_users parameter is deprecated and does nothing.
    40  * @return BP_Groups_Group $group The group object
     39 * @param array $args {
     40 *  Array of al arguments.
     41 *  @type int $group_id ID of the group.
     42 *  @type bool $load_users No longer used.
     43 *  @type bool $populate_extras Whether to fetch membership data and other
     44 *        extra information about the group. Default: false.
     45 * @return BP_Groups_Group $group The group object.
    4146 */
    4247function groups_get_group( $args = '' ) {
    … …  
    5661}
    5762
    58 /*** Group Creation, Editing & Deletion *****************************************/
     63/** Group Creation, Editing & Deletion ****************************************/
    5964
    6065/**
    … …  
    164169}
    165170
     171/**
     172 * Edit the base details for a group.
     173 *
     174 * These are the settings that appear on the first page of the group's Admin
     175 * section (Name, Description, and "Notify members...").
     176 *
     177 * @param int $group_id ID of the group.
     178 * @param string $group_name Name of the group.
     179 * @param string $group_desc Description of the group.
     180 * @param bool $notify_members Whether to send an email notification to group
     181 *        members about changes in these details.
     182 * @return bool True on success, false on failure.
     183 */
    166184function groups_edit_base_group_details( $group_id, $group_name, $group_desc, $notify_members ) {
    167185
    … …  
    185203}
    186204
     205/**
     206 * Edit the base details for a group.
     207 *
     208 * These are the settings that appear on the Settings page of the group's Admin
     209 * section (privacy settings, "enable forum", invitation status).
     210 *
     211 * @param int $group_id ID of the group.
     212 * @param bool $enable_forum Whether to enable a forum for the group.
     213 * @param string $status Group status. 'public', 'private', 'hidden'.
     214 * @param string $invite_status Optional. Who is allowed to send invitations
     215 *        to the group. 'members', 'mods', or 'admins'.
     216 * @return bool True on success, false on failure.
     217 */
    187218function groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status = false ) {
    188219
    … …  
    221252
    222253/**
    223  * Delete a group and all of its associated meta
    224  *
    225  * @global object $bp BuddyPress global settings
    226  * @param int $group_id
    227  * @since BuddyPress (1.0)
     254 * Delete a group and all of its associated metadata.
     255 *
     256 * @since BuddyPress (1.0.0)
     257 *
     258 * @param int $group_id ID of the group to delete.
     259 * @return bool True on success, false on failure.
    228260 */
    229261function groups_delete_group( $group_id ) {
    … …  
    247279}
    248280
     281/**
     282 * Check a group status (eg 'private') against the whitelist of registered statuses.
     283 *
     284 * @param string $status Status to check.
     285 * @return bool True if status is allowed, otherwise false.
     286 */
    249287function groups_is_valid_status( $status ) {
    250288    global $bp;
    … …  
    253291}
    254292
     293/**
     294 * Provide a unique, sanitized version of a group slug.
     295 *
     296 * @param string $slug Group slug to check.
     297 * @return A unique and sanitized slug.
     298 */
    255299function groups_check_slug( $slug ) {
    256300    global $bp;
    … …  
    273317
    274318/**
    275  * Get a group slug by its ID
    276  *
    277  * @param int $group_id The numeric ID of the group
    278  * @return string The group's slug
     319 * Get a group slug by its ID.
     320 *
     321 * @param int $group_id The numeric ID of the group.
     322 * @return string The group's slug.
    279323 */
    280324function groups_get_slug( $group_id ) {
    … …  
    284328
    285329/**
    286  * Get a group ID by its slug
    287  *
    288  * @since BuddyPress (1.6)
    289  *
    290  * @param string $group_slug The group's slug
    291  * @return int The ID
     330 * Get a group ID by its slug.
     331 *
     332 * @since BuddyPress (1.6.0)
     333 *
     334 * @param string $group_slug The group's slug.
     335 * @return int The ID.
    292336 */
    293337function groups_get_id( $group_slug ) {
    … …  
    295339}
    296340
    297 /*** User Actions ***************************************************************/
    298 
     341/** User Actions **************************************************************/
     342
     343/**
     344 * Remove a user from a group.
     345 *
     346 * @param int $group_id ID of the group.
     347 * @param int $user_id Optional. ID of the user. Defaults to the currently
     348 *        logged-in user.
     349 * @return bool True on success, false on failure.
     350 */
    299351function groups_leave_group( $group_id, $user_id = 0 ) {
    300352    global $bp;
    … …  
    323375}
    324376
     377/**
     378 * Add a user to a group.
     379 *
     380 * @param int $group_id ID of the group.
     381 * @param int $user_id Optional. ID of the user. Defaults to the currently
     382 *        logged-in user.
     383 * @return bool True on success, false on failure.
     384 */
    325385function groups_join_group( $group_id, $user_id = 0 ) {
    326386    global $bp;
    … …  
    373433}
    374434
    375 /*** General Group Functions ****************************************************/
    376 
     435/** General Group Functions ***************************************************/
     436
     437/**
     438 * Get a list of group administrators.
     439 *
     440 * @param int $group_id ID of the group.
     441 * @return array Info about group admins (user_id + date_modified).
     442 */
    377443function groups_get_group_admins( $group_id ) {
    378444    return BP_Groups_Member::get_group_administrator_ids( $group_id );
    379445}
    380446
     447/**
     448 * Get a list of group moderators.
     449 *
     450 * @param int $group_id ID of the group.
     451 * @return array Info about group admins (user_id + date_modified).
     452 */
    381453function groups_get_group_mods( $group_id ) {
    382454    return BP_Groups_Member::get_group_moderator_ids( $group_id );
    … …  
    489561}
    490562
     563/**
     564 * Get the member count for a group.
     565 *
     566 * @param int $group_id Group ID.
     567 * @return int Count of confirmed members for the group.
     568 */
    491569function groups_get_total_member_count( $group_id ) {
    492570    return BP_Groups_Group::get_total_member_count( $group_id );
    493571}
    494572
    495 /*** Group Fetching, Filtering & Searching  *************************************/
    496 
    497 /**
    498  * Get a collection of groups, based on the parameters passed
    499  *
    500  * @uses apply_filters_ref_array() Filter 'groups_get_groups' to modify return value
    501  * @uses BP_Groups_Group::get()
    502  * @param array $args See inline documentation for details
    503  * @return array
     573/** Group Fetching, Filtering & Searching  ************************************/
     574
     575/**
     576 * Get a collection of groups, based on the parameters passed.
     577 *
     578 * @param array $args {
     579 *     Array of arguments. Supports all arguments of
     580 *     {@link BP_Groups_Group::get()}. Where the default values differ, they
     581 *     have been described here.
     582 *     @type int $per_page Default: 20.
     583 *     @type int $page Default: 1.
     584 * }
     585 * @return array See {@link BP_Groups_Group::get()}.
    504586 */
    505587function groups_get_groups( $args = '' ) {
    … …  
    542624}
    543625
     626/**
     627 * Get the total group count for the site.
     628 *
     629 * @return int
     630 */
    544631function groups_get_total_group_count() {
    545632    if ( !$count = wp_cache_get( 'bp_total_group_count', 'bp' ) ) {
    … …  
    551638}
    552639
     640/**
     641 * Get the IDs of the groups of which a specified user is a member.
     642 *
     643 * @param int $user_id ID of the user.
     644 * @param int $limit Optional. Max number of results to return.
     645 *        Default: false (no limit).
     646 * @param int $page Optional. Page offset of results to return.
     647 *        Default: false (no limit).
     648 * @return array {
     649 *     @type array $groups Array of groups returned by paginated query.
     650 *     @type int $total Count of groups matching query.
     651 * }
     652 */
    553653function groups_get_user_groups( $user_id = 0, $pag_num = 0, $pag_page = 0 ) {
    554654
    … …  
    559659}
    560660
     661/**
     662 * Get the count of groups of which the specified user is a member.
     663 *
     664 * @param int $user_id Optional. Default: ID of the displayed user.
     665 * @return int Group count.
     666 */
    561667function groups_total_groups_for_user( $user_id = 0 ) {
    562668
    … …  
    573679
    574680/**
    575  * Returns the group object for the group currently being viewed
    576  *
    577  * @package BuddyPress
    578  * @since BuddyPress (1.5)
    579  *
    580  * @return BP_Groups_Group The current group object
     681 * Get the BP_Groups_Group object corresponding to the current group.
     682 *
     683 * @since BuddyPress (1.5.0)
     684 *
     685 * @return BP_Groups_Group The current group object.
    581686 */
    582687function groups_get_current_group() {
    … …  
    588693}
    589694
    590 /*** Group Avatars *************************************************************/
    591 
     695/** Group Avatars *************************************************************/
     696
     697/**
     698 * Generate the avatar upload directory path for a given group.
     699 *
     700 * @param int $group_id Optional. ID of the group. Default: ID of the
     701 *        current group.
     702 * @return string
     703 */
    592704function groups_avatar_upload_dir( $group_id = 0 ) {
    593705    global $bp;
    … …  
    609721}
    610722
    611 /*** Group Member Status Checks ************************************************/
    612 
     723/** Group Member Status Checks ************************************************/
     724
     725/**
     726 * Check whether a user is an admin of a given group.
     727 *
     728 * @param int $user_id ID of the user.
     729 * @param int $group_id ID of the group.
     730 * @param int|null ID of the membership if the user is an admin, otherwise null.
     731 */
    613732function groups_is_user_admin( $user_id, $group_id ) {
    614733    return BP_Groups_Member::check_is_admin( $user_id, $group_id );
    615734}
    616735
     736/**
     737 * Check whether a user is a mod of a given group.
     738 *
     739 * @param int $user_id ID of the user.
     740 * @param int $group_id ID of the group.
     741 * @param int|null ID of the membership if the user is a mod, otherwise null.
     742 */
    617743function groups_is_user_mod( $user_id, $group_id ) {
    618744    return BP_Groups_Member::check_is_mod( $user_id, $group_id );
    619745}
    620746
     747/**
     748 * Check whether a user is a member of a given group.
     749 *
     750 * @param int $user_id ID of the user.
     751 * @param int $group_id ID of the group.
     752 * @param int|null ID of the membership if the user is a member, otherwise null.
     753 */
    621754function groups_is_user_member( $user_id, $group_id ) {
    622755    return BP_Groups_Member::check_is_member( $user_id, $group_id );
    … …  
    630763 * Is the specified user the creator of the group?
    631764 *
    632  * @param int $user_id
    633  * @param int $group_id
    634765 * @since BuddyPress (1.2.6)
    635  * @uses BP_Groups_Member
     766 *
     767 * @param int $user_id ID of the user.
     768 * @param int $group_id ID of the group.
     769 * @return int|null ID of the group if the user is the creator, otherwise false.
    636770 */
    637771function groups_is_user_creator( $user_id, $group_id ) {
    … …  
    639773}
    640774
    641 /*** Group Activity Posting **************************************************/
    642 
     775/** Group Activity Posting ****************************************************/
     776
     777/**
     778 * Post an Activity status update affiliated with a group.
     779 *
     780 * @todo Should bail out when the Activity component is not active.
     781 *
     782 * @param array {
     783 *     Array of arguments.
     784 *     @type string $content The content of the update.
     785 *     @type int $user_id Optional. ID of the user posting the update. Default:
     786 *           ID of the logged-in user.
     787 *     @type int $group_id Optional. ID of the group to be affiliated with the
     788 *           update. Default: ID of the current group.
     789 * }
     790 * @return int
     791 */
    643792function groups_post_update( $args = '' ) {
    644793    global $bp;
    … …  
    683832}
    684833
    685 /*** Group Invitations *********************************************************/
    686 
     834/** Group Invitations *********************************************************/
     835
     836/**
     837 * Get IDs of users with outstanding invites to a given group from a specified user.
     838 *
     839 * @param int $user_id ID of the inviting user.
     840 * @param int $group_id ID of the group.
     841 * @return array IDs of users who have been invited to the group by the
     842 *         user but have not yet accepted.
     843 */
    687844function groups_get_invites_for_user( $user_id = 0, $limit = false, $page = false, $exclude = false ) {
    688845
    … …  
    694851
    695852/**
    696  * Gets the total group invite count for a user.
     853 * Get the total group invite count for a user.
    697854 *
    698855 * @since BuddyPress (2.0.0)
    699856 *
    700  * @param int $user_id The user ID
     857 * @param int $user_id The user ID.
    701858 * @return int
    702859 */
    … …  
    709866}
    710867
     868/**
     869 * Invite a user to a group.
     870 *
     871 * @param array $args {
     872 *     Array of arguments.
     873 *     @type int $user_id ID of the user being invited.
     874 *     @type int $group_id ID of the group to which the user is being invited.
     875 *     @type int $inviter_id Optional. ID of the inviting user. Default:
     876 *           ID of the logged-in user.
     877 *     @type string $date_modified Optional. Modified date for the invitation.
     878 *           Default: current date/time.
     879 *     @type bool $is_confirmed. Optional. Whether the invitation should be
     880 *           marked confirmed. Default: false.
     881 * }
     882 * @return bool True on success, false on failure.
     883 */
    711884function groups_invite_user( $args = '' ) {
    712885
    … …  
    747920}
    748921
     922/**
     923 * Uninvite a user from a group.
     924 *
     925 * Functionally, this is equivalent to removing a user from a group.
     926 *
     927 * @param int $user_id ID of the user.
     928 * @param int $group_id ID of the group.
     929 * @return bool True on success, false on failure.
     930 */
    749931function groups_uninvite_user( $user_id, $group_id ) {
    750932
    … …  
    762944 * Returns true if a user is already a member of the group.
    763945 *
    764  * @param int $user_id
    765  * @param int $group_id
    766  * @return bool True when the user is a member of the group, otherwise false
     946 * @param int $user_id ID of the user.
     947 * @param int $group_id ID of the group.
     948 * @return bool True when the user is a member of the group, otherwise false.
    767949 */
    768950function groups_accept_invite( $user_id, $group_id ) {
    … …  
    802984}
    803985
     986/**
     987 * Reject a group invitation.
     988 *
     989 * @param int $user_id ID of the user.
     990 * @param int $group_id ID of the group.
     991 * @return bool True on success, false on failure.
     992 */
    804993function groups_reject_invite( $user_id, $group_id ) {
    805994    if ( ! BP_Groups_Member::delete( $user_id, $group_id ) )
    … …  
    8111000}
    8121001
     1002/**
     1003 * Delete a group invitation.
     1004 *
     1005 * @param int $user_id ID of the invited user.
     1006 * @param int $group_id ID of the group.
     1007 * @return bool True on success, false on failure.
     1008 */
    8131009function groups_delete_invite( $user_id, $group_id ) {
    8141010    if ( ! BP_Groups_Member::delete_invite( $user_id, $group_id ) )
    … …  
    8201016}
    8211017
     1018/**
     1019 * Send all pending invites by a single user to a specific group.
     1020 *
     1021 * @param int $user_id ID of the inviting user.
     1022 * @param int $group_id ID of the group.
     1023 */
    8221024function groups_send_invites( $user_id, $group_id ) {
    8231025
    … …  
    8471049
    8481050/**
    849  * Check to see whether a user has already been invited to a group
    850  *
    851  * By default, the function checks for invitations that have been sent. Entering 'all' as the $type
    852  * parameter will return unsent invitations as well (useful to make sure AJAX requests are not
    853  * duplicated)
    854  *
    855  * @package BuddyPress Groups
    856  *
    857  * @param int $user_id Potential group member
    858  * @param int $group_id Potential group
    859  * @param string $type Optional. Use 'sent' to check for sent invites, 'all' to check for all
    860  * @return bool Returns true if an invitation is found
     1051 * Check to see whether a user has already been invited to a group.
     1052 *
     1053 * By default, the function checks for invitations that have been sent.
     1054 * Entering 'all' as the $type parameter will return unsent invitations as
     1055 * well (useful to make sure AJAX requests are not duplicated).
     1056 *
     1057 * @param int $user_id ID of potential group member.
     1058 * @param int $group_id ID of potential group.
     1059 * @param string $type Optional. Use 'sent' to check for sent invites, 'all' to
     1060 *        check for all. Default: 'sent'.
     1061 * @return bool True if an invitation is found, otherwise false.
    8611062 */
    8621063function groups_check_user_has_invite( $user_id, $group_id, $type = 'sent' ) {
    … …  
    8641065}
    8651066
     1067/**
     1068 * Delete all invitations to a given group.
     1069 *
     1070 * @param int $group_id ID of the group whose invitations are being deleted.
     1071 * @return int|null Number of rows records deleted on success, null on failure.
     1072 */
    8661073function groups_delete_all_group_invites( $group_id ) {
    8671074    return BP_Groups_Group::delete_all_invites( $group_id );
    8681075}
    8691076
    870 /*** Group Promotion & Banning *************************************************/
    871 
     1077/** Group Promotion & Banning *************************************************/
     1078
     1079/**
     1080 * Promote a member to a new status within a group.
     1081 *
     1082 * @param int $user_id ID of the user.
     1083 * @param int $group_id ID of the group.
     1084 * @param string $status The new status. 'mod' or 'admin'.
     1085 * @return bool True on success, false on failure.
     1086 */
    8721087function groups_promote_member( $user_id, $group_id, $status ) {
    8731088
    … …  
    8861101}
    8871102
     1103/**
     1104 * Demone a user to 'member' status within a group.
     1105 *
     1106 * @param int $user_id ID of the user.
     1107 * @param int $group_id ID of the group.
     1108 * @return bool True on success, false on failure.
     1109 */
    8881110function groups_demote_member( $user_id, $group_id ) {
    8891111
    … …  
    8981120}
    8991121
     1122/**
     1123 * Ban a member from a group.
     1124 *
     1125 * @param int $user_id ID of the user.
     1126 * @param int $group_id ID of the group.
     1127 * @return bool True on success, false on failure.
     1128 */
    9001129function groups_ban_member( $user_id, $group_id ) {
    9011130
    … …  
    9101139}
    9111140
     1141/**
     1142 * Unban a member from a group.
     1143 *
     1144 * @param int $user_id ID of the user.
     1145 * @param int $group_id ID of the group.
     1146 * @return bool True on success, false on failure.
     1147 */
    9121148function groups_unban_member( $user_id, $group_id ) {
    9131149
    … …  
    9221158}
    9231159
    924 /*** Group Removal *******************************************************/
    925 
     1160/** Group Removal *************************************************************/
     1161
     1162/**
     1163 * Remove a member from a group.
     1164 *
     1165 * @param int $user_id ID of the user.
     1166 * @param int $group_id ID of the group.
     1167 * @return bool True on success, false on failure.
     1168 */
    9261169function groups_remove_member( $user_id, $group_id ) {
    9271170
    … …  
    9361179}
    9371180
    938 /*** Group Membership ****************************************************/
    939 
     1181/** Group Membership **********************************************************/
     1182
     1183/**
     1184 * Create a group membership request.
     1185 *
     1186 * @param int $requesting_user_id ID of the user requesting membership.
     1187 * @param int $group_id ID of the group.
     1188 * @return bool True on success, false on failure.
     1189 */
    9401190function groups_send_membership_request( $requesting_user_id, $group_id ) {
    9411191
    … …  
    9791229}
    9801230
     1231/**
     1232 * Accept a pending group membership request.
     1233 *
     1234 * @param int $membership_id ID of the membership object.
     1235 * @param int $user_id Optional. ID of the user who requested membership.
     1236 *        Provide this value along with $group_id to override $membership_id.
     1237 * @param int $group_id Optional. ID of the group to which membership is being
     1238 *        requested. Provide this value along with $user_id to override
     1239 *        $membership_id.
     1240 * @return bool True on success, false on failure.
     1241 */
    9811242function groups_accept_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) {
    9821243
    … …  
    10031264}
    10041265
     1266/**
     1267 * Reject a pending group membership request.
     1268 *
     1269 * @param int $membership_id ID of the membership object.
     1270 * @param int $user_id Optional. ID of the user who requested membership.
     1271 *        Provide this value along with $group_id to override $membership_id.
     1272 * @param int $group_id Optional. ID of the group to which membership is being
     1273 *        requested. Provide this value along with $user_id to override
     1274 *        $membership_id.
     1275 * @return bool True on success, false on failure.
     1276 */
    10051277function groups_reject_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) {
    10061278    if ( !$membership = groups_delete_membership_request( $membership_id, $user_id, $group_id ) ) {
    … …  
    10131285}
    10141286
     1287/**
     1288 * Delete a pending group membership request.
     1289 *
     1290 * @param int $membership_id ID of the membership object.
     1291 * @param int $user_id Optional. ID of the user who requested membership.
     1292 *        Provide this value along with $group_id to override $membership_id.
     1293 * @param int $group_id Optional. ID of the group to which membership is being
     1294 *        requested. Provide this value along with $user_id to override
     1295 *        $membership_id.
     1296 * @return bool True on success, false on failure.
     1297 */
    10151298function groups_delete_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) {
    10161299    if ( !empty( $user_id ) && !empty( $group_id ) )
    … …  
    10251308}
    10261309
     1310/**
     1311 * Check whether a user has an outstanding membership request for a given group.
     1312 *
     1313 * @param int $user_id ID of the user.
     1314 * @param int $group_id ID of the group.
     1315 * @return int|null ID of the membership if found, otherwise false.
     1316 */
    10271317function groups_check_for_membership_request( $user_id, $group_id ) {
    10281318    return BP_Groups_Member::check_for_membership_request( $user_id, $group_id );
    10291319}
    10301320
     1321/**
     1322 * Accept all pending membership requests to a group.
     1323 *
     1324 * @param int $group_id ID of the group.
     1325 * @return bool True on success, false on failure.
     1326 */
    10311327function groups_accept_all_pending_membership_requests( $group_id ) {
    10321328    $user_ids = BP_Groups_Member::get_all_membership_request_user_ids( $group_id );
    … …  
    10431339}
    10441340
    1045 /*** Group Meta ****************************************************/
     1341/** Group Meta ****************************************************************/
    10461342
    10471343/**
    … …  
    11441440}
    11451441
    1146 /*** Group Cleanup Functions ****************************************************/
    1147 
     1442/** Group Cleanup Functions ***************************************************/
     1443
     1444/**
     1445 * Delete all group membership information for the specified user.
     1446 *
     1447 * @since BuddyPress (1.0.0)
     1448 *
     1449 * @param int $user_id ID of the user.
     1450 */
    11481451function groups_remove_data_for_user( $user_id ) {
    11491452    BP_Groups_Member::delete_all_for_user( $user_id );

  • trunk/src/bp-groups/bp-groups-loader.php

    r8982 r9027  
    1818
    1919    /**
    20      * Auto join group when non group member performs group activity
    21      *
    22      * @since BuddyPress (1.5)
     20     * Auto-join group when non group member performs group activity
     21     *
     22     * @since BuddyPress (1.5.0)
     23     * @access public
    2324     * @var bool
    2425     */
    … …  
    2627
    2728    /**
    28      * The group being currently accessed
    29      *
    30      * @since BuddyPress (1.5)
     29     * The group being currently accessed.
     30     *
     31     * @since BuddyPress (1.5.0)
     32     * @access public
    3133     * @var BP_Groups_Group
    3234     */
    … …  
    3436
    3537    /**
    36      * Default group extension
    37      *
    38      * @since BuddyPress (1.6)
     38     * Default group extension.
     39     *
     40     * @since BuddyPress (1.6.0)
     41     * @access public
    3942     * @todo Is this used anywhere? Is this a duplicate of $default_extension?
    4043     */
    … …  
    4245
    4346    /**
    44      * Default group extension
    45      *
    46      * @since BuddyPress (1.6)
     47     * Default group extension.
     48     *
     49     * @since BuddyPress (1.6.0)
     50     * @access public
    4751     * @var string
    4852     */
    … …  
    5054
    5155    /**
    52      * Illegal group names/slugs
    53      *
    54      * @since BuddyPress (1.5)
     56     * Illegal group names/slugs.
     57     *
     58     * @since BuddyPress (1.5.0)
     59     * @access public
    5560     * @var array
    5661     */
    … …  
    5863
    5964    /**
    60      * Group creation/edit steps (e.g. Details, Settings, Avatar, Invites)
    61      *
    62      * @since BuddyPress (1.5)
     65     * Group creation/edit steps (e.g. Details, Settings, Avatar, Invites).
     66     *
     67     * @since BuddyPress (1.5.0)
     68     * @access public
    6369     * @var array
    6470     */
    … …  
    6672
    6773    /**
    68      * Types of group statuses (Public, Private, Hidden)
    69      *
    70      * @since BuddyPress (1.5)
     74     * Types of group statuses (Public, Private, Hidden).
     75     *
     76     * @since BuddyPress (1.5.0)
     77     * @access public
    7178     * @var array
    7279     */
    … …  
    7481
    7582    /**
    76      * Start the groups component creation process
    77      *
    78      * @since BuddyPress (1.5)
     83     * Start the groups component creation process.
     84     *
     85     * @since BuddyPress (1.5.0)
    7986     */
    8087    public function __construct() {
    … …  
    9097
    9198    /**
    92      * Include files
     99     * Include Groups component files.
     100     *
     101     * @since BuddyPress (1.5.0)
     102     *
     103     * @see BP_Component::includes() for a description of arguments.
     104     *
     105     * @param array $includes See BP_Component::includes() for a description.
    93106     */
    94107    public function includes( $includes = array() ) {
    … …  
    115128
    116129    /**
    117      * Setup globals
     130     * Set up component global data.
    118131     *
    119132     * The BP_GROUPS_SLUG constant is deprecated, and only used here for
    120133     * backwards compatibility.
    121134     *
    122      * @since BuddyPress (1.5)
     135     * @since BuddyPress (1.5.0)
     136     *
     137     * @see BP_Component::setup_globals() for a description of arguments.
     138     *
     139     * @param array $args See BP_Component::setup_globals() for a description.
    123140     */
    124141    public function setup_globals( $args = array() ) {
    … …  
    321338
    322339    /**
    323      * Set up navigation.
    324      *
    325      * @global BuddyPress $bp The one true BuddyPress instance
     340     * Set up component navigation.
     341     *
     342     * @since BuddyPress (1.5.0)
     343     *
     344     * @see BP_Component::setup_nav() for a description of arguments.
     345     *
     346     * @param array $main_nav Optional. See BP_Component::setup_nav() for
     347     *        description.
     348     * @param array $sub_nav Optional. See BP_Component::setup_nav() for
     349     *        description.
    326350     */
    327351    public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
    … …  
    497521
    498522    /**
    499      * Set up the Toolbar
     523     * Set up the component entries in the WordPress Admin Bar.
     524     *
     525     * @see BP_Component::setup_nav() for a description of the $wp_admin_nav
     526     *      parameter array.
     527     *
     528     * @param array $wp_admin_nav See BP_Component::setup_admin_bar() for a
     529     *        description.
    500530     */
    501531    public function setup_admin_bar( $wp_admin_nav = array() ) {
    … …  
    558588
    559589    /**
    560      * Sets up the title for pages and <title>
     590     * Set up the title for pages and <title>.
    561591     */
    562592    public function setup_title() {
    … …  
    598628}
    599629
    600 
     630/**
     631 * Bootstrap the Notifications component.
     632 *
     633 * @since BuddyPress (1.5.0)
     634 */
    601635function bp_setup_groups() {
    602636    buddypress()->groups = new BP_Groups_Component();

  • trunk/src/bp-groups/bp-groups-notifications.php

    r8576 r9027  
    1717
    1818/**
    19  * Notify all group members when a group is updated
     19 * Notify all group members when a group is updated.
    2020 *
    2121 * @since BuddyPress (1.0.0)
    2222 *
    23  * @param int $group_id
     23 * @param int $group_id ID of the group.
    2424 */
    2525function groups_notification_group_updated( $group_id = 0 ) {
    … …  
    6969
    7070/**
    71  * Notify group admin about new membership request
     71 * Notify group admin about new membership request.
    7272 *
    7373 * @since BuddyPress (1.0.0)
    7474 *
    75  * @param int $requesting_user_id
    76  * @param int $admin_id
    77  * @param int $group_id
    78  * @param int $membership_id
    79  * @return boolean
     75 * @param int $requesting_user_id ID of the user requesting group membership.
     76 * @param int $admin_id ID of the group admin.
     77 * @param int $group_id ID of the group.
     78 * @param int $membership_id ID of the group membership object.
     79 * @return bool|null False on failure.
    8080 */
    8181function groups_notification_new_membership_request( $requesting_user_id = 0, $admin_id = 0, $group_id = 0, $membership_id = 0 ) {
    … …  
    145145
    146146/**
    147  * Notify member about their group membership request
     147 * Notify member about their group membership request.
    148148 *
    149149 * @since BuddyPress (1.0.0)
    150150 *
    151  * @param type $requesting_user_id
    152  * @param type $group_id
    153  * @param type $accepted
     151 * @param int $requesting_user_id ID of the user requesting group membership.
     152 * @param int $group_id ID of the group.
     153 * @param bool $accepted Optional. Whether the membership request was accepted.
     154 *        Default: true.
    154155 * @return boolean
    155156 */
    … …  
    224225
    225226/**
    226  * Notify group member they have been promoted
     227 * Notify group member they have been promoted.
    227228 *
    228229 * @since BuddyPress (1.0.0)
    229230 *
    230  * @param int $user_id
    231  * @param int $group_id
    232  * @return boolean
     231 * @param int $user_id ID of the user.
     232 * @param int $group_id ID of the group.
     233 * @return bool|null False on failure.
    233234 */
    234235function groups_notification_promoted_member( $user_id = 0, $group_id = 0 ) {
    … …  
    292293
    293294/**
    294  * Notify a member they have been invitated to a group
     295 * Notify a member they have been invited to a group.
    295296 *
    296297 * @since BuddyPress (1.0.0)
    297298 *
    298  * @param object $group
    299  * @param object $member
    300  * @param int $inviter_user_id
    301  * @return boolean
     299 * @param BP_Groups_Group $group Group object.
     300 * @param BP_Groups_Member $member Member object.
     301 * @param int $inviter_user_id ID of the user who sent the invite.
     302 * @return bool|null False on failure.
    302303 */
    303304function groups_notification_group_invites( &$group, &$member, $inviter_user_id ) {
    … …  
    375376 * @since BuddyPress (1.0.0)
    376377 *
    377  * @param string $action The kind of notification being rendered
    378  * @param int $item_id The primary item id
    379  * @param int $secondary_item_id The secondary item id
    380  * @param int $total_items The total number of messaging-related notifications waiting for the user
    381  * @param string $format 'string' for BuddyBar-compatible notifications; 'array' for WP Toolbar
     378 * @param string $action The kind of notification being rendered.
     379 * @param int $item_id The primary item ID.
     380 * @param int $secondary_item_id The secondary item ID.
     381 * @param int $total_items The total number of messaging-related notifications
     382 *        waiting for the user.
     383 * @param string $format 'string' for BuddyBar-compatible notifications; 'array'
     384 *        for WP Toolbar. Default: 'string'.
     385 * @return string
    382386 */
    383387function groups_format_notifications( $action, $item_id, $secondary_item_id, $total_items, $format = 'string' ) {
    … …  
    611615
    612616/**
    613  * Remove all notifications for any member belonging to a specific group
     617 * Remove all notifications for any member belonging to a specific group.
    614618 *
    615619 * @since BuddyPress (1.9.0)
     620 *
     621 * @param int $group_id ID of the group.
    616622 */
    617623function bp_groups_delete_group_delete_all_notifications( $group_id ) {
    … …  
    626632 *
    627633 * @since BuddyPress (2.0.0)
     634 *
     635 * @param int $user_id ID of the user.
     636 * @param int $group_id ID of the group.
    628637 */
    629638function bp_groups_delete_promotion_notifications( $user_id = 0, $group_id = 0 ) {
    … …  
    636645
    637646/**
    638  * Mark notifications read when a member accepts a group invitation
     647 * Mark notifications read when a member accepts a group invitation.
    639648 *
    640649 * @since BuddyPress (1.9.0)
    641  * @param int $user_id
    642  * @param int $group_id
     650 *
     651 * @param int $user_id ID of the user.
     652 * @param int $group_id ID of the group.
    643653 */
    644654function bp_groups_accept_invite_mark_notifications( $user_id, $group_id ) {
    … …  
    652662
    653663/**
    654  * Mark notifications read when a member views their group memberships
     664 * Mark notifications read when a member views their group memberships.
    655665 *
    656666 * @since BuddyPress (1.9.0)
    … …  
    676686
    677687/**
    678  * Mark group invitation notifications read when a member views their invitations
     688 * Mark group invitation notifications read when a member views their invitations.
    679689 *
    680690 * @since BuddyPress (1.9.0)
    … …  
    688698
    689699/**
    690  * Mark group join requests read when an admin or moderator visits the group
    691  * administration area.
     700 * Mark group join requests read when an admin or moderator visits the group administration area.
    692701 *
    693702 * @since BuddyPress (1.9.0)
    … …  
    704713 *
    705714 * @since BuddyPress (1.9.0)
    706  * @param int $user_id
     715 *
     716 * @param int $user_id ID of the user.
    707717 */
    708718function bp_groups_remove_data_for_user_notifications( $user_id ) {

  • trunk/src/bp-groups/bp-groups-screens.php

    r8737 r9027  
    44 * BuddyPress Groups 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 * Handle the display of the Groups directory index.
     19 */
    1720function groups_directory_groups_setup() {
    1821    if ( bp_is_groups_directory() ) {
    … …  
    2629add_action( 'bp_screens', 'groups_directory_groups_setup', 2 );
    2730
     31/**
     32 * Handle the loading of the My Groups page.
     33 */
    2834function groups_screen_my_groups() {
    2935
    … …  
    3339}
    3440
     41/**
     42 * Handle the loading of a user's Groups > Invites page.
     43 */
    3544function groups_screen_group_invites() {
    3645    $group_id = (int)bp_action_variable( 1 );
    … …  
    8897}
    8998
     99/**
     100 * Handle the loading of a single group's page.
     101 */
    90102function groups_screen_group_home() {
    91103
    … …  
    100112
    101113/**
    102  * This screen function handles actions related to group forums
    103  *
    104  * @package BuddyPress
     114 * This screen function handles actions related to group forums.
    105115 */
    106116function groups_screen_group_forum() {
    … …  
    400410}
    401411
     412/**
     413 * Handle the display of a group's Members page.
     414 */
    402415function groups_screen_group_members() {
    403416
    … …  
    414427}
    415428
     429/**
     430 * Handle the display of a group's Send Invites page.
     431 */
    416432function groups_screen_group_invite() {
    417433
    … …  
    490506add_action( 'bp_screens', 'groups_remove_group_invite' );
    491507
     508/**
     509 * Handle the display of a group's Request Membership page.
     510 */
    492511function groups_screen_group_request_membership() {
    493512    global $bp;
    … …  
    530549}
    531550
     551/**
     552 * Handle the display of a single group activity item.
     553 */
    532554function groups_screen_group_activity_permalink() {
    533555
    … …  
    541563add_action( 'bp_screens', 'groups_screen_group_activity_permalink' );
    542564
     565/**
     566 * Handle the display of a group's Admin pages.
     567 */
    543568function groups_screen_group_admin() {
    544569    if ( !bp_is_groups_component() || !bp_is_current_action( 'admin' ) )
    … …  
    551576}
    552577
     578/**
     579 * Handle the display of a group's admin/edit-details page.
     580 */
    553581function groups_screen_group_admin_edit_details() {
    554582
    … …  
    586614add_action( 'bp_screens', 'groups_screen_group_admin_edit_details' );
    587615
     616/**
     617 * Handle the display of a group's admin/group-settings page.
     618 */
    588619function groups_screen_group_admin_settings() {
    589620
    … …  
    629660add_action( 'bp_screens', 'groups_screen_group_admin_settings' );
    630661
     662/**
     663 * Handle the display of a group's Change Avatar page.
     664 */
    631665function groups_screen_group_admin_avatar() {
    632666
    … …  
    706740/**
    707741 * This function handles actions related to member management on the group admin.
    708  *
    709  * @package BuddyPress
    710742 */
    711743function groups_screen_group_admin_manage_members() {
    … …  
    825857add_action( 'bp_screens', 'groups_screen_group_admin_manage_members' );
    826858
     859/**
     860 * Handle the display of Admin > Membership Requests.
     861 */
    827862function groups_screen_group_admin_requests() {
    828863    $bp = buddypress();
    … …  
    873908add_action( 'bp_screens', 'groups_screen_group_admin_requests' );
    874909
     910/**
     911 * Handle the display of the Delete Group page.
     912 */
    875913function groups_screen_group_admin_delete_group() {
    876914    global $bp;
    … …  
    912950
    913951/**
    914  * Renders the group settings fields on the Notification Settings page
    915  *
    916  * @package BuddyPress
     952 * Render the group settings fields on the Notification Settings page.
    917953 */
    918954function groups_screen_notification_settings() {
    … …  
    934970            <tr>
    935971                <th class="icon"></th>
    936                 <th class="title"><?php _ex( 'Groups', 'Group settings on notification settings page', 'buddypress' ) ?></th>               
     972                <th class="title"><?php _ex( 'Groups', 'Group settings on notification settings page', 'buddypress' ) ?></th>
    937973                <th class="yes"><?php _e( 'Yes', 'buddypress' ) ?></th>
    938974                <th class="no"><?php _e( 'No', 'buddypress' )?></th>
    … …  
    9781014
    9791015/**
    980  * The main theme compat class for BuddyPress Groups
     1016 * The main theme compat class for BuddyPress Groups.
    9811017 *
    9821018 * This class sets up the necessary theme compatability actions to safely output
    9831019 * group template parts to the_title and the_content areas of a theme.
    9841020 *
    985  * @since BuddyPress (1.7)
     1021 * @since BuddyPress (1.7.0)
    9861022 */
    9871023class BP_Groups_Theme_Compat {
    9881024
    9891025    /**
    990      * Setup the groups component theme compatibility
    991      *
    992      * @since BuddyPress (1.7)
     1026     * Set up theme compatibility for the Groups component.
     1027     *
     1028     * @since BuddyPress (1.7.0)
    9931029     */
    9941030    public function __construct() {
    … …  
    9991035     * Are we looking at something that needs group theme compatability?
    10001036     *
    1001      * @since BuddyPress (1.7)
     1037     * @since BuddyPress (1.7.0)
    10021038     */
    10031039    public function is_group() {
    … …  
    10321068    }
    10331069
    1034     /** Directory *************************************************************/
     1070    /** Directory *********************************************************/
    10351071
    10361072    /**
    10371073     * Add template hierarchy to theme compat for the group directory page.
    10381074     *
    1039      * This is to mirror how WordPress has {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
    1040      *
    1041      * @since BuddyPress (1.8)
    1042      *
    1043      * @param string $templates The templates from bp_get_theme_compat_templates()
     1075     * This is to mirror how WordPress has
     1076     * {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
     1077     *
     1078     * @since BuddyPress (1.8.0)
     1079     *
     1080     * @param string $templates The templates from bp_get_theme_compat_templates().
    10441081     * @return array $templates Array of custom templates to look for.
    10451082     */
    … …  
    10581095
    10591096    /**
    1060      * Update the global $post with directory data
    1061      *
    1062      * @since BuddyPress (1.7)
     1097     * Update the global $post with directory data.
     1098     *
     1099     * @since BuddyPress (1.7.0)
    10631100     */
    10641101    public function directory_dummy_post() {
    … …  
    10801117
    10811118    /**
    1082      * Filter the_content with the groups index template part
    1083      *
    1084      * @since BuddyPress (1.7)
     1119     * Filter the_content with the groups index template part.
     1120     *
     1121     * @since BuddyPress (1.7.0)
    10851122     */
    10861123    public function directory_content() {
    … …  
    10881125    }
    10891126
    1090     /** Create ****************************************************************/
     1127    /** Create ************************************************************/
    10911128
    10921129    /**
    10931130     * Add custom template hierarchy to theme compat for the group create page.
    10941131     *
    1095      * This is to mirror how WordPress has {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
    1096      *
    1097      * @since BuddyPress (1.8)
    1098      *
    1099      * @param string $templates The templates from bp_get_theme_compat_templates()
     1132     * This is to mirror how WordPress has
     1133     * {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
     1134     *
     1135     * @since BuddyPress (1.8.0)
     1136     *
     1137     * @param string $templates The templates from bp_get_theme_compat_templates().
    11001138     * @return array $templates Array of custom templates to look for.
    11011139     */
    … …  
    11141152
    11151153    /**
    1116      * Update the global $post with create screen data
    1117      *
    1118      * @since BuddyPress (1.7)
     1154     * Update the global $post with create screen data.
     1155     *
     1156     * @since BuddyPress (1.7.0)
    11191157     */
    11201158    public function create_dummy_post() {
    … …  
    11361174
    11371175    /**
    1138      * Filter the_content with the create screen template part
    1139      *
    1140      * @since BuddyPress (1.7)
     1176     * Filter the_content with the create screen template part.
     1177     *
     1178     * @since BuddyPress (1.7.0)
    11411179     */
    11421180    public function create_content() {
    … …  
    11441182    }
    11451183
    1146     /** Single ****************************************************************/
     1184    /** Single ************************************************************/
    11471185
    11481186    /**
    11491187     * Add custom template hierarchy to theme compat for group pages.
    11501188     *
    1151      * This is to mirror how WordPress has {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
    1152      *
    1153      * @since BuddyPress (1.8)
    1154      *
    1155      * @param string $templates The templates from bp_get_theme_compat_templates()
     1189     * This is to mirror how WordPress has
     1190     * {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
     1191     *
     1192     * @since BuddyPress (1.8.0)
     1193     *
     1194     * @param string $templates The templates from bp_get_theme_compat_templates().
    11561195     * @return array $templates Array of custom templates to look for.
    11571196     */
    … …  
    11771216
    11781217    /**
    1179      * Update the global $post with single group data
    1180      *
    1181      * @since BuddyPress (1.7)
     1218     * Update the global $post with single group data.
     1219     *
     1220     * @since BuddyPress (1.7.0)
    11821221     */
    11831222    public function single_dummy_post() {
    … …  
    11961235
    11971236    /**
    1198      * Filter the_content with the single group template part
    1199      *
    1200      * @since BuddyPress (1.7)
     1237     * Filter the_content with the single group template part.
     1238     *
     1239     * @since BuddyPress (1.7.0)
    12011240     */
    12021241    public function single_content() {
Note: See TracChangeset for help on using the changeset viewer.