Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
05/19/2015 01:40:26 AM (9 years ago)
Author:
tw2113
Message:

First pass at members component docs cleanup.

See #6402.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r9819 r9877  
    22
    33/**
    4  * BuddyPress Member Functions
     4 * BuddyPress Member Functions.
    55 *
    66 * Functions specific to the members component.
    … …  
    7676 * bp_use_legacy_user_query value, returning true.
    7777 *
    78  * @param array $args {
     78 * @param array|string $args {
    7979 *     Array of arguments. All are optional. See {@link BP_User_Query} for
    8080 *     a more complete description of arguments.
    … …  
    8686 *     @type string       $meta_value      Limit to users with a meta_value (with meta_key). Default: false.
    8787 *     @type array|string $member_type     Array or comma-separated string of member types.
    88  *     @type mixed $include Limit results by user IDs. Default: false.
     88 *     @type mixed        $include        Limit results by user IDs. Default: false.
    8989 *     @type int          $per_page        Results per page. Default: 20.
    9090 *     @type int          $page            Page of results. Default: 1.
    … …  
    154154 * Return the domain for the passed user: e.g. http://example.com/members/andy/.
    155155 *
    156  * @param int $user_id The ID of the user.
    157  * @param string $user_nicename Optional. user_nicename of the user.
    158  * @param string $user_login Optional. user_login of the user.
     156 * @param int         $user_id       The ID of the user.
     157 * @param string|bool $user_nicename Optional. user_nicename of the user.
     158 * @param string|bool $user_login    Optional. user_login of the user.
     159 *
     160 * @return string
    159161 */
    160162function bp_core_get_user_domain( $user_id = 0, $user_nicename = false, $user_login = false ) {
    … …  
    194196 *
    195197 * @param int $user_id The ID of the user.
     198 *
    196199 * @return array
    197200 */
    … …  
    224227 *
    225228 * @param string $user_login user_login of the user being queried.
     229 *
    226230 * @return int
    227231 */
    … …  
    236240 *
    237241 * @param string $username user_login to check.
     242 *
    238243 * @return int|null The ID of the matched user on success, null on failure.
    239244 */
    … …  
    262267 *
    263268 * @param string $user_nicename user_nicename to check.
     269 *
    264270 * @return int|null The ID of the matched user on success, null on failure.
    265271 */
    … …  
    288294 * so it will return the user_login or user_nicename as appropriate.
    289295 *
    290  * @param int $user_id User ID to check.
    291  * @param string $user_nicename Optional. user_nicename of user being checked.
    292  * @param string $user_login Optional. user_login of user being checked.
     296 * @param int         $user_id       User ID to check.
     297 * @param string|bool $user_nicename Optional. user_nicename of user being checked.
     298 * @param string|bool $user_login    Optional. user_login of user being checked.
     299 *
    293300 * @return string|bool The username of the matched user, or false.
    294301 */
    … …  
    374381 *
    375382 * @param int $user_id User ID to check.
     383 *
    376384 * @return string|bool The username of the matched user, or false.
    377385 */
    … …  
    431439 *
    432440 * @param int $uid User ID to check.
     441 *
    433442 * @return string The email for the matched user. Empty string if no user
    434  *         matched the $uid.
     443 *                matched the $uid.
    435444 */
    436445function bp_core_get_user_email( $uid ) {
    … …  
    468477 * Optional parameters will return just the name or just the URL.
    469478 *
    470  * @param int $user_id User ID to check.
     479 * @param int  $user_id  User ID to check.
    471480 * @param bool $no_anchor Disable URL and HTML and just return full name.
    472  *        Default: false.
     481 *                        Default: false.
    473482 * @param bool $just_link Disable full name and HTML and just return the URL
    474  *        text. Default false.
     483 *                        text. Default false.
     484 *
    475485 * @return string|bool The link text based on passed parameters, or false on
    476  *         no match.
     486 *                     no match.
    477487 */
    478488function bp_core_get_userlink( $user_id, $no_anchor = false, $just_link = false ) {
    … …  
    515525 *
    516526 * @param array $user_ids
     527 *
     528 * @return array
    517529 */
    518530function bp_core_get_user_displaynames( $user_ids ) {
    … …  
    593605 *
    594606 * @param int|string $user_id_or_username User ID or username.
     607 *
    595608 * @return string|bool The display name for the user in question, or false if
    596  *         user not found.
     609 *                     user not found.
    597610 */
    598611function bp_core_get_user_displayname( $user_id_or_username ) {
    … …  
    638651 *
    639652 * @param string $email The email address for the user.
     653 *
    640654 * @return string The link to the users home base. False on no match.
    641655 */
    … …  
    657671 *
    658672 * @param string $username If BP_ENABLE_USERNAME_COMPATIBILITY_MODE is set,
    659  *        this should be user_login, otherwise it should be user_nicename.
     673 *                         this should be user_login, otherwise it should
     674 *                         be user_nicename.
     675 *
    660676 * @return string|bool The link to the user's domain, false on no match.
    661677 */
    … …  
    708724
    709725/**
    710  * Return the total number of members, limited to those members with last_activity
    711  *
    712  * @return int The number of active members
     726 * Return the total number of members, limited to those members with last_activity.
     727 *
     728 * @return int The number of active members.
    713729 */
    714730function bp_core_get_active_member_count() {
    … …  
    754770 * @since BuddyPress (1.6.0)
    755771 *
    756  * @param int $user_id The ID of the user being spammed/hammed.
    757  * @param string $status 'spam' if being marked as spam, 'ham' otherwise.
    758  * @param bool $do_wp_cleanup True to force the cleanup of WordPress content
    759  *        and status, otherwise false. Generally, this should only be false if
    760  *        WordPress is expected to have performed this cleanup independently,
    761  *        as when hooked to 'make_spam_user'.
     772 * @param int    $user_id       The ID of the user being spammed/hammed.
     773 * @param string $status        'spam' if being marked as spam, 'ham' otherwise.
     774 * @param bool   $do_wp_cleanup True to force the cleanup of WordPress content
     775 *                              and status, otherwise false. Generally, this should
     776 *                              only be false if WordPress is expected to have
     777 *                              performed this cleanup independently, as when hooked
     778 *                              to 'make_spam_user'.
     779 *
    762780 * @return bool True on success, false on failure.
    763781 */
    … …  
    884902    return true;
    885903}
    886 
    887904/**
    888905 * Hook to WP's make_spam_user and run our custom BP spam functions.
    … …  
    913930 *
    914931 * @param int $user_id The ID for the user.
     932 *
    915933 * @return bool True if spammer, otherwise false.
    916934 */
    … …  
    977995 *
    978996 * @param int $user_id The ID for the user.
     997 *
    979998 * @return bool True if deleted, otherwise false.
    980999 */
    … …  
    10481067 *
    10491068 * @param int $user_id The user ID to check.
     1069 *
    10501070 * @return bool True if active, otherwise false.
    10511071 */
    … …  
    10841104 *       bp_is_user_active().
    10851105 *
    1086  * @uses is_user_logged_in() To check if user is logged in
    1087  * @uses bp_get_displayed_user_id() To get current user ID
    1088  * @uses bp_is_user_active() To check if user is active
     1106 * @uses is_user_logged_in() To check if user is logged in.
     1107 * @uses bp_get_displayed_user_id() To get current user ID.
     1108 * @uses bp_is_user_active() To check if user is active.
    10891109 *
    10901110 * @param int $user_id The user ID to check.
     1111 *
    10911112 * @return bool True if inactive, otherwise false.
    10921113 */
    … …  
    11121133 * @since BuddyPress (1.9.0)
    11131134 *
    1114  * @param int $user_id ID of the user being updated.
    1115  * @param string $time Time of last activity, in 'Y-m-d H:i:s' format.
     1135 * @param int    $user_id ID of the user being updated.
     1136 * @param string $time    Time of last activity, in 'Y-m-d H:i:s' format.
     1137 *
    11161138 * @return bool True on success, false on failure.
    11171139 */
    … …  
    11571179 * @access private For internal use only.
    11581180 *
    1159  * @param null $retval
    1160  * @param int $object_id ID of the user.
    1161  * @param string $meta_key Meta key being fetched.
     1181 * @param null   $retval
     1182 * @param int    $object_id ID of the user.
     1183 * @param string $meta_key  Meta key being fetched.
     1184 *
     1185 * @return mixed
    11621186 */
    11631187function _bp_get_user_meta_last_activity_warning( $retval, $object_id, $meta_key ) {
    … …  
    11901214 * @access private For internal use only.
    11911215 *
    1192  * @param int $meta_id ID of the just-set usermeta row.
    1193  * @param int $object_id ID of the user.
    1194  * @param string $meta_key Meta key being fetched.
     1216 * @param int    $meta_id    ID of the just-set usermeta row.
     1217 * @param int    $object_id ID of the user.
     1218 * @param string $meta_key   Meta key being fetched.
    11951219 * @param string $meta_value Active time.
    11961220 */
    … …  
    12071231 *
    12081232 * @param int $user_id The ID of the user.
     1233 *
    12091234 * @return string Time of last activity, in 'Y-m-d H:i:s' format, or an empty
    1210  *         string if none is found.
     1235 *                string if none is found.
    12111236 */
    12121237function bp_get_user_last_activity( $user_id = 0 ) {
    … …  
    12661291 *
    12671292 * @param int $user_id ID of the user being queried.
     1293 *
    12681294 * @return array Post IDs.
    12691295 */
    … …  
    12841310 *
    12851311 * @param int $user_id Optional. ID of the user to be deleted. Default: the
    1286  *        logged-in user.
     1312 *                     logged-in user.
    12871313 * @return bool True on success, false on failure.
    12881314 */
    … …  
    13531379 *
    13541380 * @param int $user_id ID of the user who is about to be deleted.
     1381 *
    13551382 * @return bool True on success, false on failure.
    13561383 */
    … …  
    13701397 *
    13711398 * @param string $str String to be upper-cased.
     1399 *
    13721400 * @return string
    13731401 */
    … …  
    13901418 *
    13911419 * @param WP_User|WP_Error $user Either the WP_User object or the WP_Error
    1392  *        object, as passed to the 'authenticate' filter.
     1420 *                               object, as passed to the 'authenticate' filter.
     1421 *
    13931422 * @return WP_User|WP_Error If the user is not a spammer, return the WP_User
    1394  *         object. Otherwise a new WP_Error object.
     1423 *                          object. Otherwise a new WP_Error object.
    13951424 */
    13961425function bp_core_boot_spammer( $user ) {
    … …  
    14631492 * Add BuddyPress-specific items to the illegal_names array.
    14641493 *
    1465  * @param array|string $value Illegal names as being saved defined in
    1466  *        Multisite settings.
     1494 * @param array|string $value    Illegal names as being saved defined in
     1495 *                               Multisite settings.
    14671496 * @param array|string $oldvalue The old value of the option.
     1497 *
    14681498 * @return array Merged and unique array of illegal names.
    14691499 */
    … …  
    15551585 * @since BuddyPress (1.6.2)
    15561586 *
    1557  * @param string $user_email The email being checked
     1587 * @param string $user_email The email being checked.
     1588 *
    15581589 * @return bool|array True if the address passes all checks; otherwise an array
    1559  *         of error codes.
     1590 *                    of error codes.
    15601591 */
    15611592function bp_core_validate_email_address( $user_email ) {
    … …  
    16061637 * @see bp_core_validate_email_address()
    16071638 *
    1608  * @param WP_Error $errors WP_Error object.
    1609  * @param array $validation_results The return value of a validation function
    1610  *        like bp_core_validate_email_address().
     1639 * @param WP_Error $errors             WP_Error object.
     1640 * @param array    $validation_results The return value of a validation function
     1641 *                                     like bp_core_validate_email_address().
    16111642 */
    16121643function bp_core_add_validation_error_messages( WP_Error $errors, $validation_results ) {
    … …  
    16311662 * Validate a user name and email address when creating a new user.
    16321663 *
    1633  * @param string $user_name Username to validate.
     1664 * @param string $user_name  Username to validate.
    16341665 * @param string $user_email Email address to validate.
     1666 *
    16351667 * @return array Results of user validation including errors, if any.
    16361668 */
    … …  
    17361768 * @todo Why do we have this wrapper?
    17371769 *
    1738  * @param string $blog_url Blog URL requested during registration.
     1770 * @param string $blog_url   Blog URL requested during registration.
    17391771 * @param string $blog_title Blog title requested during registration.
     1772 *
    17401773 * @return array
    17411774 */
    … …  
    17601793 * @todo There appears to be a bug in the return value on success.
    17611794 *
    1762  * @param string $user_login Login name requested by the user.
     1795 * @param string $user_login    Login name requested by the user.
    17631796 * @param string $user_password Password requested by the user.
    1764  * @param string $user_email Email address entered by the user.
    1765  * @param array $usermeta Miscellaneous metadata about the user (blog-specific
    1766  *        signup data, xprofile data, etc).
     1797 * @param string $user_email    Email address entered by the user.
     1798 * @param array  $usermeta      Miscellaneous metadata about the user (blog-specific
     1799 *                              signup data, xprofile data, etc).
     1800 *
    17671801 * @return bool|WP_Error True on success, WP_Error on failure.
    17681802 */
    … …  
    18561890 *
    18571891 * @param string $blog_domain Domain requested by user.
    1858  * @param string $blog_path Path requested by user.
    1859  * @param string $blog_title Title as entered by user.
    1860  * @param string $user_name user_login of requesting user.
    1861  * @param string $user_email Email address of requesting user.
    1862  * @param string $usermeta Miscellaneous metadata for the user.
     1892 * @param string $blog_path   Path requested by user.
     1893 * @param string $blog_title  Title as entered by user.
     1894 * @param string $user_name   user_login of requesting user.
     1895 * @param string $user_email  Email address of requesting user.
     1896 * @param string $usermeta    Miscellaneous metadata for the user.
     1897 *
     1898 * @return bool
    18631899 */
    18641900function bp_core_signup_blog( $blog_domain, $blog_path, $blog_title, $user_name, $user_email, $usermeta ) {
    … …  
    18841920 *
    18851921 * @param string $key Activation key.
     1922 *
    18861923 * @return int|bool User ID on success, false on failure.
    18871924 */
    … …  
    21252162 *
    21262163 * @param int $user_id ID of the user.
     2164 *
     2165 * @return bool
    21272166 */
    21282167function bp_core_map_user_registration( $user_id ) {
    … …  
    21872226 * Send activation email to a newly registered user.
    21882227 *
    2189  * @param int $user_id ID of the new user.
     2228 * @param int    $user_id    ID of the new user.
    21902229 * @param string $user_email Email address of the new user.
    2191  * @param string $key Activation key.
     2230 * @param string $key        Activation key.
    21922231 */
    21932232function bp_core_signup_send_validation_email( $user_id, $user_email, $key ) {
    … …  
    22482287 * Display a "resend email" link when an unregistered user attempts to log in.
    22492288 *
    2250  * @param WP_User|WP_Error $user Either the WP_User or the WP_Error object
    2251  * @param string $username The inputted, attempted username.
    2252  * @param string $password The inputted, attempted password.
     2289 * @since BuddyPress (1.2.2)
     2290 *
     2291 * @param WP_User|WP_Error $user     Either the WP_User or the WP_Error object.
     2292 * @param string           $username The inputted, attempted username.
     2293 * @param string           $password The inputted, attempted password.
     2294 *
    22532295 * @return WP_User|WP_Error
    2254  *
    2255  * @since BuddyPress (1.2.2)
    22562296 */
    22572297function bp_core_signup_disable_inactive( $user = null, $username = '', $password ='' ) {
    … …  
    25262566 * @since BuddyPress (2.2.0)
    25272567 *
    2528  * @param  string $member_type The name of the member type.
     2568 * @param string $member_type The name of the member type.
     2569 *
    25292570 * @return object A member type object.
    25302571 */
    … …  
    25532594 *                               element from the array needs to match; 'and' means all elements
    25542595 *                               must match. Accepts 'or' or 'and'. Default 'and'.
     2596 *
    25552597 * @return array A list of member type names or objects.
    25562598 */
    … …  
    26602702 * @since BuddyPress (2.2.0)
    26612703 *
    2662  * @param  int               $user_id ID of the user.
    2663  * @param  bool              $single  Optional. Whether to return a single type string. If multiple types are found
    2664  *                                    for the user, the oldest one will be returned. Default: true.
     2704 * @param int               $user_id ID of the user.
     2705 * @param bool              $single  Optional. Whether to return a single type string. If multiple types are found
     2706 *                                   for the user, the oldest one will be returned. Default: true.
     2707 *
    26652708 * @return string|array|bool On success, returns a single member type (if $single is true) or an array of member
    26662709 *                           types (if $single is false). Returns false on failure.
    … …  
    27042747 * @since BuddyPress (2.3.0)
    27052748 *
    2706  * @param  int    $user_id     $user_id ID of the user.
    2707  * @param  string $member_type Member Type.
     2749 * @param int    $user_id     $user_id ID of the user.
     2750 * @param string $member_type Member Type.
     2751 *
    27082752 * @return bool Whether the user has the given member type.
    27092753 */
    … …  
    27292773 * @since BuddyPress (2.2.0)
    27302774 *
    2731  * @param  int $user_id ID of the user.
     2775 * @param int $user_id ID of the user.
     2776 *
    27322777 * @return See {@see bp_set_member_type()}.
    27332778 */
Note: See TracChangeset for help on using the changeset viewer.