Skip to:
Content

BuddyPress.org

Changeset 7444


Ignore:
Timestamp:
10/19/2013 09:58:33 AM (10 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-core. See #5022

Location:
trunk/bp-core
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-core/bp-core-caps.php

    r7228 r7444  
    22
    33/**
    4  * BuddyPress Capabilites
     4 * BuddyPress Capabilites.
    55 *
    66 * @package BuddyPress
    … …  
    1212
    1313/**
    14  * Adds capabilities to WordPress user roles.
     14 * Add capabilities to WordPress user roles.
    1515 *
    1616 * This is called on plugin activation.
    1717 *
    18  * @since BuddyPress (1.6)
    19  *
    20  * @uses get_role() To get the administrator, default and moderator roles
    21  * @uses WP_Role::add_cap() To add various capabilities
    22  * @uses do_action() Calls 'bp_add_caps'
     18 * @since BuddyPress (1.6.0)
     19 *
     20 * @uses get_role() To get the administrator, default and moderator roles.
     21 * @uses WP_Role::add_cap() To add various capabilities.
     22 * @uses do_action() Calls 'bp_add_caps'.
    2323 */
    2424function bp_add_caps() {
    … …  
    4040
    4141/**
    42  * Removes capabilities from WordPress user roles.
     42 * Remove capabilities from WordPress user roles.
    4343 *
    4444 * This is called on plugin deactivation.
    4545 *
    46  * @since BuddyPress (1.6)
    47  *
    48  * @uses get_role() To get the administrator and default roles
    49  * @uses WP_Role::remove_cap() To remove various capabilities
    50  * @uses do_action() Calls 'bp_remove_caps'
     46 * @since BuddyPress (1.6.0)
     47 *
     48 * @uses get_role() To get the administrator and default roles.
     49 * @uses WP_Role::remove_cap() To remove various capabilities.
     50 * @uses do_action() Calls 'bp_remove_caps'.
    5151 */
    5252function bp_remove_caps() {
    … …  
    6868
    6969/**
    70  * Maps community caps to built in WordPress caps
    71  *
    72  * @since BuddyPress (1.6)
    73  *
    74  * @param array $caps Capabilities for meta capability
    75  * @param string $cap Capability name
    76  * @param int $user_id User id
    77  * @param mixed $args Arguments
    78  * @uses get_post() To get the post
    79  * @uses get_post_type_object() To get the post type object
    80  * @uses apply_filters() Calls 'bp_map_meta_caps' with caps, cap, user id and
    81  *                        args
    82  * @return array Actual capabilities for meta capability
     70 * Map community caps to built in WordPress caps.
     71 *
     72 * @since BuddyPress (1.6.0)
     73 *
     74 * @see WP_User::has_cap() for description of the arguments passed to the
     75 *      'map_meta_cap' filter.
     76 * @uses get_post() To get the post.
     77 * @uses get_post_type_object() To get the post type object.
     78 * @uses apply_filters() Calls 'bp_map_meta_caps' with caps, cap, user ID and
     79 *       args.
     80 *
     81 * @param array $caps See {@link WP_User::has_cap()}.
     82 * @param string $cap See {@link WP_User::has_cap()}.
     83 * @param int $user_id See {@link WP_User::has_cap()}.
     84 * @param mixed $args See {@link WP_User::has_cap()}.
     85 * @return array Actual capabilities for meta capability. See {@link WP_User::has_cap()}.
    8386 */
    8487function bp_map_meta_caps( $caps, $cap, $user_id, $args ) {
    … …  
    8790
    8891/**
    89  * Return community capabilities
    90  *
    91  * @since BuddyPress (1.6)
    92  *
    93  * @uses apply_filters() Calls 'bp_get_community_caps' with the capabilities
    94  * @return array Forum capabilities
     92 * Return community capabilities.
     93 *
     94 * @since BuddyPress (1.6.0)
     95 *
     96 * @uses apply_filters() Calls 'bp_get_community_caps' with the capabilities.
     97 *
     98 * @return array Community capabilities.
    9599 */
    96100function bp_get_community_caps() {
    … …  
    103107
    104108/**
    105  * Returns an array of capabilities based on the role that is being requested.
    106  *
    107  * @since BuddyPress (1.6)
    108  *
    109  * @param string $role Optional. Defaults to The role to load caps for
    110  * @uses apply_filters() Allow return value to be filtered
    111  *
    112  * @return array Capabilities for $role
     109 * Return an array of capabilities based on the role that is being requested.
     110 *
     111 * @since BuddyPress (1.6.0)
     112 *
     113 * @uses apply_filters() Allow return value to be filtered.
     114 *
     115 * @param string $role The role for which you're loading caps.
     116 * @return array Capabilities for $role.
    113117 */
    114118function bp_get_caps_for_role( $role = '' ) {
    … …  
    139143
    140144/**
    141  * Give a user the default 'Forum Participant' role when creating a topic/reply
    142  * on a site they do not have a role or capability on.
    143  *
    144  * @since BuddyPress (1.6)
    145  *
    146  * @global BuddyPress $bp
     145 * Set a default role for the current user.
     146 *
     147 * Give a user the default role when creating content on a site they do not
     148 * already have a role or capability on.
     149 *
     150 * @since BuddyPress (1.6.0)
     151 *
     152 * @global BuddyPress $bp Global BuddyPress settings object.
    147153 *
    148154 * @uses is_multisite()
    … …  
    172178
    173179/**
    174  * Whether current user has a capability or role. Can be passed blog ID, or will
    175  * use the root blod by default
    176  *
    177  * @since BuddyPress (1.6)
     180 * Check whether the current user has a given capability.
     181 *
     182 * Can be passed blog ID, or will use the root blog by default.
     183 *
     184 * @since BuddyPress (1.6.0)
    178185 *
    179186 * @param string $capability Capability or role name.
    180  * @param int $blog_id Blog ID
    181  * @return bool
     187 * @param int $blog_id Optional. Blog ID. Defaults to the BP root blog.
     188 * @return bool True if the user has the cap for the given blog.
    182189 */
    183190function bp_current_user_can( $capability, $blog_id = 0 ) {
    … …  
    193200
    194201/**
    195  * Temporary implementation of 'bp_moderate' cap
    196  *
    197  * In BuddyPress 1.6, the 'bp_moderate' cap was introduced. In order to enforce that
    198  * bp_current_user_can( 'bp_moderate' ) always returns true for Administrators, we must manually
    199  * add the 'bp_moderate' cap to the list of user caps for Admins.
    200  *
    201  * Note that this level of enforcement is only necessary in the case of non-Multisite. This is
    202  * because WordPress automatically assigns every capability - and thus 'bp_moderate' - to Super
    203  * Admins on a Multisite installation. See WP_User::has_cap().
    204  *
    205  * This implementation of 'bp_moderate' is temporary, until BuddyPress properly matches caps to
    206  * roles and stores them in the database. Plugin authors: Do not use this function.
    207  *
    208  * @since BuddyPress (1.6)
     202 * Temporary implementation of 'bp_moderate' cap.
     203 *
     204 * In BuddyPress 1.6, the 'bp_moderate' cap was introduced. In order to
     205 * enforce that bp_current_user_can( 'bp_moderate' ) always returns true for
     206 * Administrators, we must manually add the 'bp_moderate' cap to the list of
     207 * user caps for Admins.
     208 *
     209 * Note that this level of enforcement is only necessary in the case of
     210 * non-Multisite. This is because WordPress automatically assigns every
     211 * capability - and thus 'bp_moderate' - to Super Admins on a Multisite
     212 * installation. See {@link WP_User::has_cap()}.
     213 *
     214 * This implementation of 'bp_moderate' is temporary, until BuddyPress properly
     215 * matches caps to roles and stores them in the database. Plugin authors: Do
     216 * not use this function.
     217 *
     218 * @access private
     219 * @since BuddyPress (1.6.0)
     220 *
    209221 * @see WP_User::has_cap()
    210  * @access private
    211  *
    212  * @param array $allcaps The caps that WP associates with the given role
    213  * @param array $caps The caps being tested for in WP_User::has_cap()
    214  * @param array $args Miscellaneous arguments passed to the user_has_cap filter
    215  * @return array $allcaps The user's cap list, with 'bp_moderate' appended, if relevant
     222 *
     223 * @param array $allcaps The caps that WP associates with the given role.
     224 * @param array $caps The caps being tested for in WP_User::has_cap().
     225 * @param array $args Miscellaneous arguments passed to the user_has_cap filter.
     226 * @return array $allcaps The user's cap list, with 'bp_moderate' appended, if relevant.
    216227 */
    217228function _bp_enforce_bp_moderate_cap_for_admins( $caps = array(), $cap = '', $user_id = 0, $args = array() ) {
    … …  
    241252 * This is called on plugin activation.
    242253 *
    243  * @since BuddyPress (1.6)
    244  *
    245  * @deprecated since version 1.7
     254 * @since BuddyPress (1.6.0)
     255 * @deprecated 1.7.0
    246256 */
    247257function bp_add_roles() {
    … …  
    254264 * This is called on plugin deactivation.
    255265 *
    256  * @since BuddyPress (1.6)
    257  *
    258  * @deprecated since version 1.7
     266 * @since BuddyPress (1.6.0)
     267 * @deprecated 1.7.0
    259268 */
    260269function bp_remove_roles() {
    … …  
    264273
    265274/**
    266  * The participant role for registered users without roles
     275 * The participant role for registered users without roles.
    267276 *
    268277 * This is primarily for multisite compatibility when users without roles on
    269  * sites that have global communities enabled
     278 * sites that have global communities enabled.
    270279 *
    271280 * @since BuddyPress (1.6)
    272  *
    273  * @deprecated since version 1.7
     281 * @deprecated 1.7.0
    274282 */
    275283function bp_get_participant_role() {
    … …  
    278286
    279287/**
    280  * The moderator role for BuddyPress users
    281  *
    282  * @since BuddyPress (1.6)
    283  *
    284  * @deprecated since version 1.7
     288 * The moderator role for BuddyPress users.
     289 *
     290 * @since BuddyPress (1.6.0)
     291 * @deprecated 1.7.0
    285292 */
    286293function bp_get_moderator_role() {

  • trunk/bp-core/bp-core-classes.php

    r7427 r7444  
    11<?php
    22/**
    3  * Core component classes
     3 * Core component classes.
    44 *
    55 * @package BuddyPress
    … …  
    1111
    1212/**
    13  * BuddyPress User Query class
     13 * BuddyPress User Query class.
    1414 *
    1515 * Used for querying users in a BuddyPress context, in situations where
    … …  
    1717 * etc.
    1818 *
    19  * Accepted parameters:
    20  *   type        - Determines sort order. Select from 'newest', 'active',
    21  *                     'online', 'random', 'popular', 'alphabetical'
    22  *   per_page        - Number of results to return
    23  *   page            - Page offset (together with per_page)
    24  *   user_id         - Pass a single numeric user id to limit results to
    25  *                     friends of that user. Requires the Friends component
    26  *   search_terms    - Terms to search by. Search happens across xprofile
    27  *                     fields. Requires XProfile component
    28  *   include         - An array or comma-separated list of user ids. Results
    29  *                     will be limited to users in this list
    30  *   exclude         - An array or comma-separated list of user ids. Results
    31  *                     will not include any users in this list
    32  *   user_ids        - An array or comma-separated list of user ids. When
    33  *                     this parameter is passed, it will override all other
    34  *                     parameters; BP User objects will be constructed using
    35  *                     these IDs only
    36  *   meta_key        - Limit results to users that have usermeta associated
    37  *                     with this meta_key. Usually used with meta_value
    38  *   meta_value      - When used with meta_key, limits results to users whose
    39  *                     usermeta value associated with meta_key matches
    40  *                     meta_value
    41  *   populate_extras - Boolean. True if you want to fetch extra metadata about
    42  *                     returned users, such as total group and friend counts
    43  *   count_total     - Determines how BP_User_Query will do a count of total
    44  *                     users matching the other filter criteria. Default value
    45  *                     is 'count_query', which does a separate SELECT COUNT
    46  *                     query to determine the total. 'sql_count_found_rows'
    47  *                     uses SQL_COUNT_FOUND_ROWS and SELECT FOUND_ROWS(). Pass
    48  *                     an empty string to skip the total user count query.
     19 * @since BuddyPress (1.7.0)
    4920 *
    50  * @since BuddyPress (1.7)
     21 * @param array $query {
     22 *     Query arguments. All items are optional.
     23 *     @type string $type Determines sort order. Select from 'newest', 'active',
     24 *           'online', 'random', 'popular', 'alphabetical'. Default: 'newest'.
     25 *     @type int $per_page Number of results to return. Default: 0 (no limit).
     26 *     @type int $page Page offset (together with $per_page). Default: 0 (no
     27 *           limit).
     28 *     @type int $user_id ID of a user. If present, and if the friends
     29 *           component is activated, results will be limited to the friends of
     30 *           that user. Default: 0.
     31 *     @type string|bool $search_terms Terms to search by. Search happens
     32 *           across xprofile fields. Requires XProfile component.
     33 *           Default: false.
     34 *     @type array|string|bool $include An array or comma-separated list of
     35 *           user IDs to which query should be limited.
     36 *           Default: false.
     37 *     @type array|string|bool $exclude An array or comma-separated list of
     38 *           user IDs that will be excluded from query results. Default: false.
     39 *     @type array|string|bool $user_ids An array or comma-separated list of
     40 *           IDs corresponding to the users that should be returned. When this
     41 *           parameter is passed, it will override all others; BP User objects
     42 *           will be constructed using these IDs only. Default: false.
     43 *     @type string|bool $meta_key Limit results to users that have usermeta
     44 *           associated with this meta_key. Usually used with $meta_value.
     45 *           Default: false.
     46 *     @type string|bool $meta_value When used with $meta_key, limits results
     47 *           to users whose usermeta value associated with $meta_key matches
     48 *           $meta_value. Default: false.
     49 *     @type bool $populate_extras True if you want to fetch extra metadata
     50 *           about returned users, such as total group and friend counts.
     51 *     @type string $count_total Determines how BP_User_Query will do a count
     52 *           of total users matching the other filter criteria. Default value
     53 *           is 'count_query', which does a separate SELECT COUNT query to
     54 *           determine the total. 'sql_count_found_rows' uses
     55 *           SQL_COUNT_FOUND_ROWS and SELECT FOUND_ROWS(). Pass an empty string
     56 *           to skip the total user count query.
     57 * }
    5158 */
    5259class BP_User_Query {
    … …  
    5562
    5663    /**
    57      * Unaltered params as passed to the constructor
    58      *
    59      * @since BuddyPress (1.8)
     64     * Unaltered params as passed to the constructor.
     65     *
     66     * @since BuddyPress (1.8.0)
    6067     * @var array
    6168     */
    … …  
    6370
    6471    /**
    65      * Array of variables to query with
    66      *
    67      * @since BuddyPress (1.7)
     72     * Array of variables to query with.
     73     *
     74     * @since BuddyPress (1.7.0)
    6875     * @var array
    6976     */
    … …  
    7178
    7279    /**
    73      * List of found users and their respective data
    74      *
    75      * @since BuddyPress (1.7)
    76      * @access public To allow components to manipulate them
     80     * List of found users and their respective data.
     81     *
     82     * @access public To allow components to manipulate them.
     83     * @since BuddyPress (1.7.0)
    7784     * @var array
    7885     */
    … …  
    8087
    8188    /**
    82      * Total number of found users for the current query
    83      *
    84      * @since BuddyPress (1.7)
    85      * @access public To allow components to manipulate it
     89     * Total number of found users for the current query.
     90     *
     91     * @access public To allow components to manipulate it.
     92     * @since BuddyPress (1.7.0)
    8693     * @var int
    8794     */
    … …  
    8996
    9097    /**
    91      * List of found user ID's
    92      *
    93      * @since BuddyPress (1.7)
    94      * @access public To allow components to manipulate it
     98     * List of found user IDs.
     99     *
     100     * @access public To allow components to manipulate it.
     101     * @since BuddyPress (1.7.0)
    95102     * @var array
    96103     */
    … …  
    98105
    99106    /**
    100      * SQL clauses for the user ID query
    101      *
    102      * @since BuddyPress (1.7)
    103      * @access public To allow components to manipulate it
    104      * @var array()
     107     * SQL clauses for the user ID query.
     108     *
     109     * @access public To allow components to manipulate it.
     110     * @since BuddyPress (1.7.0)
     111     * @var array
    105112     */
    106113    public $uid_clauses = array();
    107114
    108115    /**
    109      * SQL database column name to order by
    110      *
    111      * @since BuddyPress (1.7)
     116     * SQL database column name to order by.
     117     *
     118     * @since BuddyPress (1.7.0)
    112119     * @var string
    113120     */
    … …  
    117124     * Standard response when the query should not return any rows.
    118125     *
    119      * @since BuddyPress (1.7)
    120126     * @access protected
     127     * @since BuddyPress (1.7.0)
    121128     * @var string
    122129     */
    … …  
    127134
    128135    /**
    129      * Constructor
    130      *
    131      * @since BuddyPress (1.7)
    132      *
    133      * @param string|array $query The query variables
     136     * Constructor.
     137     *
     138     * @since BuddyPress (1.7.0)
     139     *
     140     * @param string|array $query See {@link BP_User_Query}.
    134141     */
    135142    public function __construct( $query = null ) {
    … …  
    184191
    185192    /**
    186      * Allow extending classes to set up action/filter hooks
     193     * Allow extending classes to set up action/filter hooks.
    187194     *
    188195     * When extending BP_User_Query, you may need to use some of its
    … …  
    193200     * your own class if you need a place where your extending class can
    194201     * add its hooks early in the query-building process. See
    195      * BP_Group_Member_Query::setup_hooks() for an example.
    196      *
    197      * @since BuddyPress (1.8)
     202     * {@link BP_Group_Member_Query::setup_hooks()} for an example.
     203     *
     204     * @since BuddyPress (1.8.0)
    198205     */
    199206    public function setup_hooks() {}
    200207
    201208    /**
    202      * Prepare the query for user_ids
    203      *
    204      * @since BuddyPress (1.7)
     209     * Prepare the query for user_ids.
     210     *
     211     * @since BuddyPress (1.7.0)
    205212     */
    206213    public function prepare_user_ids_query() {
    … …  
    403410
    404411    /**
     412     * Query for IDs of users that match the query parameters.
     413     *
    405414     * Perform a database query to specifically get only user IDs, using
    406415     * existing query variables set previously in the constructor.
    … …  
    408417     * Also used to quickly perform user total counts.
    409418     *
    410      * @since BuddyPress (1.7)
     419     * @since BuddyPress (1.7.0)
    411420     */
    412421    public function do_user_ids_query() {
    … …  
    431440
    432441    /**
    433      * Perform a database query using the WP_User_Query() object, using existing
    434      * fields, variables, and user ID's set previously in this class.
    435      *
    436      * @since BuddyPress (1.7)
     442     * Use WP_User_Query() to pull data for the user IDs retrieved in the main query.
     443     *
     444     * @since BuddyPress (1.7.0)
    437445     */
    438446    public function do_wp_user_query() {
    … …  
    468476
    469477    /**
    470      * Fetches the ids of users to put in the IN clause of the main query
     478     * Fetch the IDs of users to put in the IN clause of the main query.
    471479     *
    472480     * By default, returns the value passed to it
    … …  
    474482     * standalone method means that extending classes can override the
    475483     * logic, parsing together their own user_id limits with the 'include'
    476      * ids passed to the class constructor. See BP_Group_Member_Query for
    477      * an example.
    478      *
    479      * @since BuddyPress (1.8)
    480      * @param array Sanitized array of user ids, as passed to the 'include'
    481      *   parameter of the class constructor
     484     * ids passed to the class constructor. See {@link BP_Group_Member_Query}
     485     * for an example.
     486     *
     487     * @since BuddyPress (1.8.0)
     488     *
     489     * @param array Sanitized array of user IDs, as passed to the 'include'
     490     *        parameter of the class constructor.
    482491     * @return array The list of users to which the main query should be
    483      *   limited
     492     *         limited.
    484493     */
    485494    public function get_include_ids( $include = array() ) {
    … …  
    489498    /**
    490499     * Perform a database query to populate any extra metadata we might need.
     500     *
    491501     * Different components will hook into the 'bp_user_query_populate_extras'
    492502     * action to loop in the things they want.
    493503     *
    494      * @since BuddyPress (1.7)
    495      *
    496      * @global BuddyPress $bp
    497      * @global WPDB $wpdb
    498      * @return
     504     * @since BuddyPress (1.7.0)
     505     *
     506     * @global BuddyPress $bp Global BuddyPress settings object.
     507     * @global WPDB $wpdb Global WordPress database access object.
    499508     */
    500509    public function populate_extras() {
    … …  
    606615
    607616/**
     617 * Fetch data about a BuddyPress user.
     618 *
    608619 * BP_Core_User class can be used by any component. It will fetch useful
    609620 * details for any user when provided with a user_id.
    … …  
    615626 *    $user_status = $user->status;
    616627 *    etc.
    617  *
    618  * @package BuddyPress Core
    619628 */
    620629class BP_Core_User {
    … …  
    714723     * Profile information for the specific user.
    715724     *
    716      * @since BuddyPress (1.2)
     725     * @since BuddyPress (1.2.0)
    717726     * @var array
    718727     */
    … …  
    724733     * Class constructor.
    725734     *
    726      * @param integer $user_id The ID for the user
    727      * @param boolean $populate_extras Whether to fetch extra information such as group/friendship counts or not.
     735     * @param integer $user_id The ID for the user being queried.
     736     * @param bool $populate_extras Whether to fetch extra information
     737     *        such as group/friendship counts or not. Default: false.
    728738     */
    729739    public function __construct( $user_id, $populate_extras = false ) {
    … …  
    738748    }
    739749
    740     /** Private Methods *******************************************************/
    741 
    742750    /**
    743751     * Populate the instantiated class with data based on the User ID provided.
    744752     *
    745      * @uses bp_core_get_userurl() Returns the URL with no HTML markup for a user based on their user id
    746      * @uses bp_core_get_userlink() Returns a HTML formatted link for a user with the user's full name as the link text
    747      * @uses bp_core_get_user_email() Returns the email address for the user based on user ID
    748      * @uses bp_get_user_meta() BP function returns the value of passed usermeta name from usermeta table
     753     * @uses bp_core_get_userurl() Returns the URL with no HTML markup for
     754     *       a user based on their user id.
     755     * @uses bp_core_get_userlink() Returns a HTML formatted link for a
     756     *       user with the user's full name as the link text.
     757     * @uses bp_core_get_user_email() Returns the email address for the
     758     *       user based on user ID.
     759     * @uses bp_get_user_meta() BP function returns the value of passed
     760     *       usermeta name from usermeta table.
    749761     * @uses bp_core_fetch_avatar() Returns HTML formatted avatar for a user
    750      * @uses bp_profile_last_updated_date() Returns the last updated date for a user.
     762     * @uses bp_profile_last_updated_date() Returns the last updated date
     763     *       for a user.
    751764     */
    752765    public function populate() {
    … …  
    795808    }
    796809
     810    /**
     811     * Fetch xprofile data for the current user.
     812     *
     813     * @see BP_XProfile_ProfileData::get_all_for_user() for description of
     814     *      return value.
     815     *
     816     * @return array See {@link BP_XProfile_Profile_Data::get_all_for_user()}.
     817     */
    797818    public function get_profile_data() {
    798819        return BP_XProfile_ProfileData::get_all_for_user( $this->id );
    … …  
    801822    /** Static Methods ********************************************************/
    802823
     824    /**
     825     * Get a list of users that match the query parameters.
     826     *
     827     * Since BuddyPress 1.7, use {@link BP_User_Query} instead.
     828     *
     829     * @deprecated 1.7.0 Use {@link BP_User_Query}.
     830     *
     831     * @see BP_User_Query for a description of parameters, most of which
     832     *      are used there in the same way.
     833     *
     834     * @param string $type See {@link BP_User_Query}.
     835     * @param int $limit See {@link BP_User_Query}. Default: 0.
     836     * @param int $page See {@link BP_User_Query}. Default: 1.
     837     * @param int $user_id See {@link BP_User_Query}. Default: 0.
     838     * @param mixed $include See {@link BP_User_Query}. Default: false.
     839     * @param string|bool $search_terms See {@link BP_User_Query}.
     840     *        Default: false.
     841     * @param bool $populate_extras See {@link BP_User_Query}.
     842     *        Default: true.
     843     * @param mixed $exclude See {@link BP_User_Query}. Default: false.
     844     * @param string|bool $meta_key See {@link BP_User_Query}.
     845     *        Default: false.
     846     * @param string|bool $meta_value See {@link BP_User_Query}.
     847     *        Default: false.
     848     * @return array {
     849     *     @type int $total_users Total number of users matched by query
     850     *           params.
     851     *     @type array $paged_users The current page of users matched by
     852     *           query params.
     853     * }
     854     */
    803855    public static function get_users( $type, $limit = 0, $page = 1, $user_id = 0, $include = false, $search_terms = false, $populate_extras = true, $exclude = false, $meta_key = false, $meta_value = false ) {
    804856        global $wpdb, $bp;
    … …  
    9761028
    9771029    /**
    978      * Fetches the user details for all the users who username starts with the letter given.
    979      *
    980      * @global BuddyPress $bp The one true BuddyPress instance
    981      * @global wpdb $wpdb WordPress database object
     1030     * Fetch the details for all users whose usernames start with the given letter.
     1031     *
     1032     * @global BuddyPress $bp The one true BuddyPress instance.
     1033     * @global wpdb $wpdb WordPress database object.
     1034     *
    9821035     * @param string $letter The letter the users names are to start with.
    983      * @param integer $limit The number of users we wish to retrive.
    984      * @param integer $page The page number we are currently on, used in conjunction with $limit to get the start position for the limit.
    985      * @param boolean $populate_extras Populate extra user fields?
    986      * @param string $exclude Comma-separated IDs of users whose results aren't to be fetched.
     1036     * @param int $limit The number of users we wish to retrive.
     1037     * @param int $page The page number we are currently on, used in
     1038     *        conjunction with $limit to get the start position for the
     1039     *        limit.
     1040     * @param bool $populate_extras Populate extra user fields?
     1041     * @param string $exclude Comma-separated IDs of users whose results
     1042     *        aren't to be fetched.
    9871043     * @return mixed False on error, otherwise associative array of results.
    988      * @static
    9891044     */
    9901045    public static function get_users_by_letter( $letter, $limit = null, $page = 1, $populate_extras = true, $exclude = '' ) {
    … …  
    10431098
    10441099    /**
    1045      * Get details of specific users from the database
    1046      *
    1047      * @global wpdb $wpdb WordPress database object
    1048      * @param array $user_ids The user IDs of the users who we wish to fetch information on.
    1049      * @param integer $limit The limit of results we want.
    1050      * @param integer $page The page we are on for pagination.
    1051      * @param boolean $populate_extras Populate extra user fields?
    1052      * @return array Associative array
    1053      * @static
     1100     * Get details of specific users from the database.
     1101     *
     1102     * Use {@link BP_User_Query} with the 'user_ids' param instead.
     1103     *
     1104     * @global wpdb $wpdb WordPress database object.
     1105     * @param array $user_ids The user IDs of the users who we wish to
     1106     *        fetch information on.
     1107     * @param int $limit The limit of results we want.
     1108     * @param int $page The page we are on for pagination.
     1109     * @param bool $populate_extras Populate extra user fields?
     1110     * @return array Associative array.
    10541111     */
    10551112    public static function get_specific_users( $user_ids, $limit = null, $page = 1, $populate_extras = true ) {
    … …  
    10881145     * Find users who match on the value of an xprofile data.
    10891146     *
    1090      * @global BuddyPress $bp The one true BuddyPress instance
    1091      * @global wpdb $wpdb WordPress database object
    1092      * @param string $search_terms The terms to search the profile table value column for.
     1147     * @global BuddyPress $bp The one true BuddyPress instance.
     1148     * @global wpdb $wpdb WordPress database object.
     1149     *
     1150     * @param string $search_terms The terms to search the profile table
     1151     *        value column for.
    10931152     * @param integer $limit The limit of results we want.
    10941153     * @param integer $page The page we are on for pagination.
    10951154     * @param boolean $populate_extras Populate extra user fields?
    1096      * @return array Associative array
    1097      * @static
     1155     * @return array Associative array.
    10981156     */
    10991157    public static function search_users( $search_terms, $limit = null, $page = 1, $populate_extras = true ) {
    … …  
    11311189     * Accepts multiple user IDs to fetch data for.
    11321190     *
    1133      * @global BuddyPress $bp The one true BuddyPress instance
    1134      * @global wpdb $wpdb WordPress database object
    1135      * @param array $paged_users an array of stdClass containing the users
    1136      * @param string $user_ids the user ids to select information about
    1137      * @param string $type the type of fields we wish to get
     1191     * @global BuddyPress $bp The one true BuddyPress instance.
     1192     * @global wpdb $wpdb WordPress database object.
     1193     *
     1194     * @param array $paged_users An array of stdClass containing the users.
     1195     * @param string $user_ids The user ids to select information about.
     1196     * @param string $type The type of fields we wish to get.
    11381197     * @return mixed False on error, otherwise associative array of results.
    1139      * @static
    11401198     */
    11411199    public static function get_user_extras( &$paged_users, &$user_ids, $type = false ) {
    … …  
    12171275     * Get WordPress user details for a specified user.
    12181276     *
    1219      * @global wpdb $wpdb WordPress database object
    1220      * @param integer $user_id User ID
    1221      * @return array Associative array
    1222      * @static
     1277     * @global wpdb $wpdb WordPress database object.
     1278     *
     1279     * @param integer $user_id User ID.
     1280     * @return array Associative array.
    12231281     */
    12241282    public static function get_core_userdata( $user_id ) {
    … …  
    14681526
    14691527/**
    1470  * BP_Button
     1528 * API to create BuddyPress buttons.
    14711529 *
    1472  * API to create BuddyPress buttons
     1530 * @since BuddyPress (1.2.6)
    14731531 *
    1474  * component: Which component this button is for
    1475  * must_be_logged_in: Button only appears for logged in users
    1476  * block_self: Button will not appear when viewing your own profile.
    1477  * wrapper: div|span|p|li|false for no wrapper
    1478  * wrapper_id: The DOM ID of the button wrapper
    1479  * wrapper_class: The DOM class of the button wrapper
    1480  * link_href: The destination link of the button
    1481  * link_title: Title of the button
    1482  * link_id: The DOM ID of the button
    1483  * link_class: The DOM class of the button
    1484  * link_rel: The DOM rel of the button
    1485  * link_text: The text of the button
    1486  * contents: The contents of the button
    1487  *
    1488  * @package BuddyPress Core
    1489  * @since BuddyPress (1.2.6)
     1532 * @param array $args {
     1533 *     Array of arguments.
     1534 *     @type string $id String describing the button type.
     1535 *     @type string $component The name of the component the button belongs to.
     1536 *           Default: 'core'.
     1537 *     @type bool $must_be_logged_in Optional. Does the user need to be logged
     1538 *           in to see this button? Default: true.
     1539 *     @type bool $block_self Optional. True if the button should be hidden
     1540 *           when a user is viewing his own profile. Default: true.
     1541 *     @type string|bool $wrapper Optional. HTML element type that should wrap
     1542 *           the button: 'div', 'span', 'p', or 'li'. False for no wrapper at
     1543 *           all. Default: 'div'.
     1544 *     @type string $wrapper_id Optional. DOM ID of the button wrapper element.
     1545 *           Default: ''.
     1546 *     @type string $wrapper_class Optional. DOM class of the button wrapper
     1547 *           element. Default: ''.
     1548 *     @type string $link_href Optional. Destination link of the button.
     1549 *           Default: ''.
     1550 *     @type string $link_class Optional. DOM class of the button. Default: ''.
     1551 *     @type string $link_id Optional. DOM ID of the button. Default: ''.
     1552 *     @type string $link_rel Optional. DOM 'rel' attribute of the button.
     1553 *           Default: ''.
     1554 *     @type string $link_title Optional. Title attribute of the button.
     1555 *           Default: ''.
     1556 *     @type string $link_text Optional. Text to appear on the button.
     1557 *           Default: ''.
     1558 * }
    14901559 */
    14911560class BP_Button {
    … …  
    14941563
    14951564    /**
    1496      * The button ID
    1497      *
    1498      * @var integer
     1565     * The button ID.
     1566     *
     1567     * @var string
    14991568     */
    15001569    public $id = '';
    15011570
    15021571    /**
    1503      * The component name that button belongs to.
     1572     * The name of the component that the button belongs to.
    15041573     *
    15051574     * @var string
    … …  
    15101579     * Does the user need to be logged in to see this button?
    15111580     *
    1512      * @var boolean
     1581     * @var bool
    15131582     */
    15141583    public $must_be_logged_in = true;
    15151584
    15161585    /**
    1517      * True or false if the button should not be displayed while viewing your
    1518      * own profile.
    1519      *
    1520      * @var boolean
     1586     * Whether the button should be hidden when viewing your own profile.
     1587     *
     1588     * @var bool
    15211589     */
    15221590    public $block_self = true;
    … …  
    15251593
    15261594    /**
    1527      * What type of DOM element to use for a wrapper.
    1528      *
    1529      *
    1530      * @var mixed div|span|p|li, or false for no wrapper
     1595     * The type of DOM element to use for a wrapper.
     1596     *
     1597     * @var string|bool 'div', 'span', 'p', 'li', or false for no wrapper.
    15311598     */
    15321599    public $wrapper = 'div';
    15331600
    15341601    /**
    1535      * The DOM class of the button wrapper
     1602     * The DOM class of the button wrapper.
    15361603     *
    15371604     * @var string
    … …  
    15401607
    15411608    /**
    1542      * The DOM ID of the button wrapper
     1609     * The DOM ID of the button wrapper.
    15431610     *
    15441611     * @var string
    … …  
    15491616
    15501617    /**
    1551      * The destination link of the button
     1618     * The destination link of the button.
    15521619     *
    15531620     * @var string
    … …  
    15561623
    15571624    /**
    1558      * The DOM class of the button link
     1625     * The DOM class of the button link.
    15591626     *
    15601627     * @var string
    … …  
    15631630
    15641631    /**
    1565      * The DOM ID of the button link
     1632     * The DOM ID of the button link.
    15661633     *
    15671634     * @var string
    … …  
    15701637
    15711638    /**
    1572      * The DOM rel value of the button link
     1639     * The DOM rel value of the button link.
    15731640     *
    15741641     * @var string
    … …  
    15771644
    15781645    /**
    1579      * Title of the button link
     1646     * Title of the button link.
    15801647     *
    15811648     * @var string
    … …  
    15841651
    15851652    /**
    1586      * The contents of the button link
     1653     * The contents of the button link.
    15871654     *
    15881655     * @var string
    … …  
    15971664
    15981665    /**
    1599      * Builds the button based on class parameters:
     1666     * Builds the button based on class parameters.
    16001667     *
    16011668     * @since BuddyPress (1.2.6)
    16021669     *
    1603      * @param array $args
    1604      * @return bool False if not allowed
     1670     * @param array $args See {@BP_Button}.
     1671     * @return bool|null Returns false when the button is not allowed for
     1672     *         the current context.
    16051673     */
    16061674    public function __construct( $args = '' ) {
    … …  
    16751743
    16761744    /**
    1677      * Return contents of button
     1745     * Return the markup for the generated button.
    16781746     *
    16791747     * @since BuddyPress (1.2.6)
    16801748     *
    1681      * @return string
     1749     * @return string Button markup.
    16821750     */
    16831751    public function contents() {
    … …  
    16861754
    16871755    /**
    1688      * Output contents of button
     1756     * Output the markup of button.
    16891757     *
    16901758     * @since BuddyPress (1.2.6)
    … …  
    16971765
    16981766/**
    1699  * BP_Embed
     1767 * Enable oEmbeds in BuddyPress contexts.
    17001768 *
    17011769 * Extends WP_Embed class for use with BuddyPress.
    17021770 *
    1703  * @package BuddyPress Core
    1704  * @since BuddyPress (1.5)
     1771 * @since BuddyPress (1.5.0)
     1772 *
    17051773 * @see WP_Embed
    17061774 */
    … …  
    17101778     * Constructor
    17111779     *
    1712      * @global unknown $wp_embed
     1780     * @global WP_Embed $wp_embed
    17131781     */
    17141782    public function __construct() {
    … …  
    17471815     * The {@link do_shortcode()} callback function.
    17481816     *
    1749      * Attempts to convert a URL into embed HTML. Starts by checking the URL against the regex of the registered embed handlers.
    1750      * Next, checks the URL against the regex of registered {@link WP_oEmbed} providers if oEmbed discovery is false.
    1751      * If none of the regex matches and it's enabled, then the URL will be passed to {@link BP_Embed::parse_oembed()} for oEmbed parsing.
     1817     * Attempts to convert a URL into embed HTML. Starts by checking the
     1818     * URL against the regex of the registered embed handlers. Next, checks
     1819     * the URL against the regex of registered {@link WP_oEmbed} providers
     1820     * if oEmbed discovery is false. If none of the regex matches and it's
     1821     * enabled, then the URL will be passed to {@link BP_Embed::parse_oembed()}
     1822     * for oEmbed parsing.
    17521823     *
    17531824     * @uses wp_parse_args()
    … …  
    18131884
    18141885    /**
    1815      * Base function so BP components / plugins can parse links to be embedded.
     1886     * Base function so BP components/plugins can parse links to be embedded.
     1887     *
    18161888     * View an example to add support in {@link bp_activity_embed()}.
    18171889     *
    18181890     * @uses apply_filters() Filters cache.
    18191891     * @uses do_action() To save cache.
    1820      * @uses wp_oembed_get() Connects to oEmbed provider and returns HTML on success.
    1821      * @uses WP_Embed::maybe_make_link() Process URL for hyperlinking on oEmbed failure.
     1892     * @uses wp_oembed_get() Connects to oEmbed provider and returns HTML
     1893     *       on success.
     1894     * @uses WP_Embed::maybe_make_link() Process URL for hyperlinking on
     1895     *       oEmbed failure.
     1896     *
    18221897     * @param int $id ID to do the caching for.
    18231898     * @param string $url The URL attempting to be embedded.
    18241899     * @param array $attr Shortcode attributes from {@link WP_Embed::shortcode()}.
    1825      * @param array $rawattr Untouched shortcode attributes from {@link WP_Embed::shortcode()}.
     1900     * @param array $rawattr Untouched shortcode attributes from
     1901     *        {@link WP_Embed::shortcode()}.
    18261902     * @return string The embed HTML on success, otherwise the original URL.
    18271903     */
    … …  
    18611937
    18621938/**
    1863  * Create HTML list of BP nav items
     1939 * Create HTML list of BP nav items.
    18641940 *
    1865  * @since BuddyPress (1.7)
     1941 * @since BuddyPress (1.7.0)
    18661942 */
    18671943class BP_Walker_Nav_Menu extends Walker_Nav_Menu {
    1868     /**
    1869      * @since BuddyPress (1.7)
     1944
     1945    /**
     1946     * Description of fields indexes for building markup.
     1947     *
     1948     * @since BuddyPress (1.7.0)
    18701949     * @var array
    18711950     */
    … …  
    18731952
    18741953    /**
    1875      * @since BuddyPress (1.7)
     1954     * Tree type.
     1955     *
     1956     * @since BuddyPress (1.7.0)
    18761957     * @var string
    18771958     */
    … …  
    18811962     * Display array of elements hierarchically.
    18821963     *
    1883      * This method is almost identical to the version in {@link Walker::walk()}. The only change is on one line
    1884      * which has been commented. An IF was comparing 0 to a non-empty string which was preventing child elements
     1964     * This method is almost identical to the version in {@link Walker::walk()}.
     1965     * The only change is on one line which has been commented. An IF was
     1966     * comparing 0 to a non-empty string which was preventing child elements
    18851967     * being grouped under their parent menu element.
    18861968     *
    1887      * This caused a problem for BuddyPress because our primary/secondary navigations doesn't have a unique numerical
    1888      * ID that describes a hierarchy (we use a slug). Obviously, WordPress Menus use Posts, and those have ID/post_parent.
    1889      *
    1890      * @param array $elements
    1891      * @param int $max_depth
    1892      * @return string
     1969     * This caused a problem for BuddyPress because our primary/secondary
     1970     * navigations don't have a unique numerical ID that describes a
     1971     * hierarchy (we use a slug). Obviously, WordPress Menus use Posts, and
     1972     * those have ID/post_parent.
     1973     *
     1974     * @since BuddyPress (1.7.0)
     1975     *
    18931976     * @see Walker::walk()
    1894      * @since BuddyPress (1.7)
     1977     *
     1978     * @param array $elements See {@link Walker::walk()}.
     1979     * @param int $max_depth See {@link Walker::walk()}.
     1980     * @return string See {@link Walker::walk()}.
    18951981     */
    18961982    public function walk( $elements, $max_depth ) {
    … …  
    19722058
    19732059    /**
    1974      * Displays the current <li> that we are on.
    1975      *
    1976      * @param string $output Passed by reference. Used to append additional content.
     2060     * Display the current <li> that we are on.
     2061     *
     2062     * @see Walker::start_el() for complete description of parameters .
     2063     *
     2064     * @since BuddyPress (1.7.0)
     2065     *
     2066     * @param string $output Passed by reference. Used to append
     2067     *        additional content.
    19772068     * @param object $item Menu item data object.
    1978      * @param int $depth Depth of menu item. Used for padding. Optional, defaults to 0.
    1979      * @param array $args Optional
     2069     * @param int $depth Depth of menu item. Used for padding. Optional,
     2070     *        defaults to 0.
     2071     * @param array $args Optional. See {@link Walker::start_el()}.
    19802072     * @param int $current_page Menu item ID. Optional.
    1981      * @since BuddyPress (1.7)
    19822073     */
    19832074    public function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
    … …  
    20132104
    20142105/**
    2015  * Create a set of BuddyPress-specific links for use in the Menus admin UI
     2106 * Create a set of BuddyPress-specific links for use in the Menus admin UI.
    20162107 *
    2017  * Borrowed heavily from WP's Walker_Nav_Menu_Checklist, but modified so as not
     2108 * Borrowed heavily from {@link Walker_Nav_Menu_Checklist}, but modified so as not
    20182109 * to require an actual post type or taxonomy, and to force certain CSS classes
    20192110 *
    … …  
    20212112 */
    20222113class BP_Walker_Nav_Menu_Checklist extends Walker_Nav_Menu {
     2114
     2115    /**
     2116     * Constructor.
     2117     *
     2118     * @see Walker_Nav_Menu::__construct() for a description of parameters.
     2119     *
     2120     * @param array $fields See {@link Walker_Nav_Menu::__construct()}.
     2121     */
    20232122    public function __construct( $fields = false ) {
    20242123        if ( $fields ) {
    … …  
    20272126    }
    20282127
     2128    /**
     2129     * Create the markup to start a tree level.
     2130     *
     2131     * @see Walker_Nav_Menu::start_lvl() for description of parameters.
     2132     *
     2133     * @param string $output See {@Walker_Nav_Menu::start_lvl()}.
     2134     * @param int $depth See {@Walker_Nav_Menu::start_lvl()}.
     2135     * @param array $args See {@Walker_Nav_Menu::start_lvl()}.
     2136     */
    20292137    public function start_lvl( &$output, $depth = 0, $args = array() ) {
    20302138        $indent = str_repeat( "\t", $depth );
    … …  
    20322140    }
    20332141
     2142    /**
     2143     * Create the markup to end a tree level.
     2144     *
     2145     * @see Walker_Nav_Menu::end_lvl() for description of parameters.
     2146     *
     2147     * @param string $output See {@Walker_Nav_Menu::end_lvl()}.
     2148     * @param int $depth See {@Walker_Nav_Menu::end_lvl()}.
     2149     * @param array $args See {@Walker_Nav_Menu::end_lvl()}.
     2150     */
    20342151    public function end_lvl( &$output, $depth = 0, $args = array() ) {
    20352152        $indent = str_repeat( "\t", $depth );
    … …  
    20382155
    20392156    /**
    2040      * @see Walker::start_el()
    2041      *
    2042      * @param string $output Passed by reference. Used to append additional content.
     2157     * Create the markup to start an element.
     2158     *
     2159     * @see Walker::start_el() for description of parameters.
     2160     *
     2161     * @param string $output Passed by reference. Used to append additional
     2162     *        content.
    20432163     * @param object $item Menu item data object.
    20442164     * @param int $depth Depth of menu item. Used for padding.
    2045      * @param object $args
     2165     * @param object $args See {@Walker::start_el()}.
     2166     * @param int $id See {@Walker::start_el()}.
    20462167     */
    20472168    function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
Note: See TracChangeset for help on using the changeset viewer.