Skip to:
Content

BuddyPress.org

Changeset 7451


Ignore:
Timestamp:
10/20/2013 07:21:38 PM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-core. See #5022

Location:
trunk/bp-core
Files:
3 edited

Legend:

Unmodified
Added
Removed

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

    r7347 r7451  
    22
    33/**
    4  * BuddyPress Core Loader
    5  *
    6  * Core contains the commonly used functions, classes, and API's
     4 * BuddyPress Core Loader.
     5 *
     6 * Core contains the commonly used functions, classes, and APIs.
    77 *
    88 * @package BuddyPress
    … …  
    1616
    1717    /**
    18      * Start the members component creation process
    19      *
    20      * @since BuddyPress (1.5)
     18     * Start the members component creation process.
     19     *
     20     * @since BuddyPress (1.5.0)
    2121     *
    2222     * @uses BP_Core::bootstrap()
    … …  
    3333
    3434    /**
    35      * Populate the global data needed before BuddyPress can continue
     35     * Populate the global data needed before BuddyPress can continue.
    3636     *
    3737     * This involves figuring out the currently required, active, deactive,
    3838     * and optional components.
    3939     *
    40      * @since BuddyPress (1.5)
     40     * @since BuddyPress (1.5.0)
    4141     */
    4242    private function bootstrap() {
    … …  
    109109    }
    110110
     111    /**
     112     * Include bp-core files.
     113     *
     114     * @see BP_Component::includes() for description of parameters.
     115     *
     116     * @param array $includes See {@link BP_Component::includes()}.
     117     */
    111118    public function includes( $includes = array() ) {
    112119
    … …  
    122129
    123130    /**
     131     * Set up bp-core global settings.
     132     *
    124133     * Sets up a majority of the BuddyPress globals that require a minimal
    125134     * amount of processing, meaning they cannot be set in the BuddyPress class.
    126135     *
    127      * @since BuddyPress (1.5)
     136     * @since BuddyPress (1.5.0)
     137     *
     138     * @see BP_Component::setup_globals() for description of parameters.
     139     *
     140     * @param array $args See {@link BP_Component::setup_globals()}.
    128141     */
    129142    public function setup_globals( $args = array() ) {
    … …  
    185198
    186199    /**
    187      * Setup BuddyBar navigation
    188      *
    189      * @since BuddyPress (1.5)
    190      */
    191     public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
     200     * Set up component navigation.
     201     *
     202     * @since BuddyPress (1.5.0)
     203     *
     204     * @see BP_Component::setup_nav() for a description of arguments.
     205     *
     206     * @param array $main_nav Optional. See BP_Component::setup_nav() for
     207     *        description.
     208     * @param array $sub_nav Optional. See BP_Component::setup_nav() for
     209     *        description.
     210     */
     211         public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
    192212        $bp = buddypress();
    193213
    … …  
    228248
    229249/**
    230  * Setup the BuddyPress Core component
    231  *
    232  * @since BuddyPress (1.6)
    233  *
    234  * @global BuddyPress $bp
     250 * Set up the BuddyPress Core component.
     251 *
     252 * @since BuddyPress (1.6.0)
     253 *
     254 * @global BuddyPress $bp BuddyPress global settings object.
    235255 */
    236256function bp_setup_core() {

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

    r6342 r7451  
    11<?php
    22/**
    3  * BuddyPress Moderation Functions
     3 * BuddyPress Moderation Functions.
    44 *
    55 * @package BuddyPress
    66 * @subpackage Core
    7  * @since BuddyPress (1.6)
     7 * @since BuddyPress (1.6.0)
    88 */
    99
    … …  
    1414
    1515/**
    16  * Check for flooding
     16 * Check for flooding.
    1717 *
    1818 * Check to make sure that a user is not making too many posts in a short amount
    1919 * of time.
    2020 *
    21  * @param int $user_id User id to check for flood
    22  * @return bool True if there is no flooding, true if there is
    23  * @since BuddyPress (1.6)
    24  * @uses current_user_can() To check if the current user can throttle
    25  * @uses bp_get_option() To get the throttle time
    26  * @uses get_transient() To get the last posted transient of the ip
    27  * @uses get_user_meta() To get the last posted meta of the user
     21 * @since BuddyPress (1.6.0)
     22 *
     23 * @uses current_user_can() To check if the current user can throttle.
     24 * @uses bp_get_option() To get the throttle time.
     25 * @uses get_transient() To get the last posted transient of the ip.
     26 * @uses get_user_meta() To get the last posted meta of the user.
     27 *
     28 * @param int $user_id User id to check for flood.
     29 * @return bool True if there is no flooding, false if there is.
    2830 */
    2931function bp_core_check_for_flood( $user_id = 0 ) {
    … …  
    4547
    4648/**
    47  * Check for moderation keys and too many links
    48  *
    49  * @param int $user_id Topic or reply author ID
    50  * @param string $title The title of the content
    51  * @param string $content The content being posted
    52  * @return bool True if test is passed, false if fail
    53  * @since BuddyPress (1.6)
    54  * @uses bp_current_author_ip() To get current user IP address
    55  * @uses bp_current_author_ua() To get current user agent
    56  * @uses bp_current_user_can() Allow super admins to bypass blacklist
     49 * Check for moderation keys and too many links.
     50 *
     51 * @since BuddyPress (1.6.0)
     52 *
     53 * @uses bp_current_author_ip() To get current user IP address.
     54 * @uses bp_current_author_ua() To get current user agent.
     55 * @uses bp_current_user_can() Allow super admins to bypass blacklist.
     56 *
     57 * @param int $user_id Topic or reply author ID.
     58 * @param string $title The title of the content.
     59 * @param string $content The content being posted.
     60 * @return bool True if test is passed, false if fail.
    5761 */
    5862function bp_core_check_for_moderation( $user_id = 0, $title = '', $content = '' ) {
    … …  
    151155
    152156/**
    153  * Checks for blocked keys
    154  *
    155  * @param int $user_id Topic or reply author ID
    156  * @param string $title The title of the content
    157  * @param string $content The content being posted
    158  * @return bool True if test is passed, false if fail
    159  * @uses bp_current_author_ip() To get current user IP address
    160  * @uses bp_current_author_ua() To get current user agent
    161  * @uses bp_current_user_can() Allow super admins to bypass blacklist
    162  * @since BuddyPress (1.6)
     157 * Check for blocked keys.
     158 *
     159 * @since BuddyPress (1.6.0)
     160 *
     161 * @uses bp_current_author_ip() To get current user IP address.
     162 * @uses bp_current_author_ua() To get current user agent.
     163 * @uses bp_current_user_can() Allow super admins to bypass blacklist.
     164 *
     165 * @param int $user_id Topic or reply author ID.
     166 * @param string $title The title of the content.
     167 * @param string $content The content being posted.
     168 * @return bool True if test is passed, false if fail.
    163169 */
    164170function bp_core_check_for_blacklist( $user_id = 0, $title = '', $content = '' ) {
    … …  
    239245
    240246/**
    241  * Get the current-user IP address
    242  *
    243  * @return string
    244  * @since BuddyPress (1.6)
     247 * Get the current user's IP address.
     248 *
     249 * @since BuddyPress (1.6.0)
     250 *
     251 * @return string IP address.
    245252 */
    246253function bp_core_current_user_ip() {
    … …  
    251258
    252259/**
    253  * Get the current-user user-agent
    254  *
    255  * @return string
    256  * @since BuddyPress (1.6)
     260 * Get the current user's user-agent.
     261 *
     262 * @since BuddyPress (1.6.0)
     263 *
     264 * @return string User agent string.
    257265 */
    258266function bp_core_current_user_ua() {

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

    r7228 r7451  
    22
    33/**
    4  * BuddyPress Options
     4 * BuddyPress Options.
    55 *
    66 * @package BuddyPress
    … …  
    1212
    1313/**
    14  * Get the default site options and their values
    15  *
    16  * @since BuddyPress (1.6)
    17  *
    18  * @return array Filtered option names and values
     14 * Get the default site options and their values.
     15 *
     16 * @since BuddyPress (1.6.0)
     17 *
     18 * @return array Filtered option names and values.
    1919 */
    2020function bp_get_default_options() {
    … …  
    8787
    8888/**
    89  * Add default options
     89 * Add default options when BuddyPress is first activated.
    9090 *
    9191 * Hooked to bp_activate, it is only called once when BuddyPress is activated.
    9292 * This is non-destructive, so existing settings will not be overridden.
    9393 *
    94  * @since BuddyPress (1.6)
    95  *
    96  * @uses bp_get_default_options() To get default options
    97  * @uses add_option() Adds default options
    98  * @uses do_action() Calls 'bp_add_options'
     94 * Currently unused.
     95 *
     96 * @since BuddyPress (1.6.0)
     97 *
     98 * @uses bp_get_default_options() To get default options.
     99 * @uses add_option() Adds default options.
     100 * @uses do_action() Calls 'bp_add_options'.
    99101 */
    100102function bp_add_options() {
    … …  
    112114
    113115/**
    114  * Delete default options
     116 * Delete default options.
    115117 *
    116118 * Hooked to bp_uninstall, it is only called once when BuddyPress is uninstalled.
    117119 * This is destructive, so existing settings will be destroyed.
    118120 *
    119  * @since BuddyPress (1.6)
    120  *
    121  * @uses bp_get_default_options() To get default options
    122  * @uses delete_option() Removes default options
    123  * @uses do_action() Calls 'bp_delete_options'
     121 * Currently unused.
     122 *
     123 * @since BuddyPress (1.6.0)
     124 *
     125 * @uses bp_get_default_options() To get default options.
     126 * @uses delete_option() Removes default options.
     127 * @uses do_action() Calls 'bp_delete_options'.
    124128 */
    125129function bp_delete_options() {
    … …  
    137141
    138142/**
    139  * Add filters to each BuddyPress option and allow them to be overloaded from
    140  * inside the $bp->options array.
    141  *
    142  * @since BuddyPress (1.6)
    143  *
    144  * @uses bp_get_default_options() To get default options
    145  * @uses add_filter() To add filters to 'pre_option_{$key}'
    146  * @uses do_action() Calls 'bp_add_option_filters'
     143 * Add filters to each BP option, allowing them to be overloaded from inside the $bp->options array.
     144 *
     145 * Currently unused.
     146 *
     147 * @since BuddyPress (1.6.0)
     148 *
     149 * @uses bp_get_default_options() To get default options.
     150 * @uses add_filter() To add filters to 'pre_option_{$key}'.
     151 * @uses do_action() Calls 'bp_add_option_filters'.
    147152 */
    148153function bp_setup_option_filters() {
    … …  
    160165
    161166/**
    162  * Filter default options and allow them to be overloaded from inside the
    163  * $bp->options array.
     167 * Filter default options and allow them to be overloaded from inside the $bp->options array.
     168 *
     169 * Currently unused.
    164170 *
    165171 * @since BuddyPress (1.6)
    … …  
    187193
    188194/**
    189  * Retrieve an option
    190  *
    191  * This is a wrapper for get_blog_option(), which in turn stores settings data (such as bp-pages)
    192  * on the appropriate blog, given your current setup.
     195 * Retrieve an option.
     196 *
     197 * This is a wrapper for {@link get_blog_option()}, which in turn stores settings data
     198 * (such as bp-pages) on the appropriate blog, given your current setup.
    193199 *
    194200 * The 'bp_get_option' filter is primarily for backward-compatibility.
    195201 *
    196  * @package BuddyPress
    197  * @since BuddyPress (1.5)
     202 * @since BuddyPress (1.5.0)
    198203 *
    199204 * @uses bp_get_root_blog_id()
    200  * @param string $option_name The option to be retrieved
    201  * @param string $default Optional. Default value to be returned if the option isn't set
    202  * @return mixed The value for the option
     205 *
     206 * @param string $option_name The option to be retrieved.
     207 * @param string $default Optional. Default value to be returned if the option
     208 *        isn't set. See {@link get_blog_option()}.
     209 * @return mixed The value for the option.
    203210 */
    204211function bp_get_option( $option_name, $default = '' ) {
    … …  
    209216
    210217/**
    211  * Save an option
    212  *
    213  * This is a wrapper for update_blog_option(), which in turn stores settings data (such as bp-pages)
    214  * on the appropriate blog, given your current setup.
    215  *
    216  * @package BuddyPress
    217  * @since BuddyPress (1.5)
     218 * Save an option.
     219 *
     220 * This is a wrapper for {@link update_blog_option()}, which in turn stores
     221 * settings data (such as bp-pages) on the appropriate blog, given your current
     222 * setup.
     223 *
     224 * @since BuddyPress (1.5.0)
    218225 *
    219226 * @uses bp_get_root_blog_id()
    220  * @param string $option_name The option key to be set
    221  * @param string $value The value to be set
     227 *
     228 * @param string $option_name The option key to be set.
     229 * @param string $value The value to be set.
    222230 */
    223231function bp_update_option( $option_name, $value ) {
    … …  
    226234
    227235/**
    228  * Delete an option
    229  *
    230  * This is a wrapper for delete_blog_option(), which in turn deletes settings data (such as
    231  * bp-pages) on the appropriate blog, given your current setup.
    232  *
    233  * @package BuddyPress
    234  * @since BuddyPress (1.5)
     236 * Delete an option.
     237 *
     238 * This is a wrapper for {@link delete_blog_option()}, which in turn deletes
     239 * settings data (such as bp-pages) on the appropriate blog, given your current
     240 * setup.
     241 *
     242 * @since BuddyPress (1.5.0)
    235243 *
    236244 * @uses bp_get_root_blog_id()
    237  * @param string $option_name The option key to be set
     245 *
     246 * @param string $option_name The option key to be deleted.
    238247 */
    239248function bp_delete_option( $option_name ) {
    … …  
    242251
    243252/**
    244  * When switching from single to multisite we need to copy blog options to
    245  * site options.
    246  *
    247  * This function is no longer used
    248  *
    249  * @package BuddyPress Core
    250  * @deprecated Since BuddyPress (1.6)
     253 * Copy BP options from a single site to multisite config.
     254 *
     255 * Run when switching from single to multisite and we need to copy blog options
     256 * to site options.
     257 *
     258 * This function is no longer used.
     259 *
     260 * @deprecated 1.6.0
    251261 */
    252262function bp_core_activate_site_options( $keys = array() ) {
    … …  
    275285
    276286/**
     287 * Fetch global BP options.
     288 *
    277289 * BuddyPress uses common options to store configuration settings. Many of these
    278290 * settings are needed at run time. Instead of fetching them all and adding many
    279291 * initial queries to each page load, let's fetch them all in one go.
    280292 *
    281  * @package BuddyPress Core
    282  * @todo Use settings API and audit these methods
     293 * @todo Use settings API and audit these methods.
     294 *
     295 * @return array $root_blog_options_meta List of options.
    283296 */
    284297function bp_core_get_root_options() {
    … …  
    376389 * Is profile sycing disabled?
    377390 *
    378  * @since BuddyPress (1.6)
    379  *
    380  * @param bool $default Optional.Default value true
    381  *
    382  * @uses bp_get_option() To get the profile sync option
    383  * @return bool Is profile sync enabled or not
     391 * @since BuddyPress (1.6.0)
     392 *
     393 * @uses bp_get_option() To get the profile sync option.
     394 *
     395 * @param bool $default Optional. Fallback value if not found in the database.
     396 *        Default: true.
     397 * @return bool True if profile sync is enabled, otherwise false.
    384398 */
    385399function bp_disable_profile_sync( $default = true ) {
    … …  
    390404 * Is the Toolbar hidden for logged out users?
    391405 *
    392  * @since BuddyPress (1.6)
    393  *
    394  * @param bool $default Optional.Default value true
    395  *
    396  * @uses bp_get_option() To get the logged out Toolbar option
    397  * @return bool Is logged out Toolbar enabled or not
     406 * @since BuddyPress (1.6.0)
     407 *
     408 * @uses bp_get_option() To get the logged out Toolbar option.
     409 *
     410 * @param bool $default Optional. Fallback value if not found in the database.
     411 *        Default: true.
     412 * @return bool True if the admin bar should be hidden for logged-out users,
     413 *         otherwise false.
    398414 */
    399415function bp_hide_loggedout_adminbar( $default = true ) {
    … …  
    404420 * Are members able to upload their own avatars?
    405421 *
    406  * @since BuddyPress (1.6)
    407  *
    408  * @param bool $default Optional. Default value true
    409  *
    410  * @uses bp_get_option() To get the avatar uploads option
    411  * @return bool Are avatar uploads allowed?
     422 * @since BuddyPress (1.6.0)
     423 *
     424 * @uses bp_get_option() To get the avatar uploads option.
     425 *
     426 * @param bool $default Optional. Fallback value if not found in the database.
     427 *        Default: true.
     428 * @return bool True if avatar uploads are disabled, otherwise false.
    412429 */
    413430function bp_disable_avatar_uploads( $default = true ) {
    … …  
    418435 * Are members able to delete their own accounts?
    419436 *
    420  * @since BuddyPress (1.6)
    421  *
    422  * @param bool $default Optional. Default value
    423  *
    424  * @uses bp_get_option() To get the account deletion option
    425  * @return bool Is account deletion allowed?
     437 * @since BuddyPress (1.6.0)
     438 *
     439 * @uses bp_get_option() To get the account deletion option.
     440 *
     441 * @param bool $default Optional. Fallback value if not found in the database.
     442 *        Default: true.
     443 * @return bool True if users are able to delete their own accounts, otherwise
     444 *         false.
    426445 */
    427446function bp_disable_account_deletion( $default = false ) {
    … …  
    432451 * Are blog and forum activity stream comments disabled?
    433452 *
    434  * @since BuddyPress (1.6)
    435  *
    436  * @param bool $default Optional. Default value false
    437  * @todo split and move into blog and forum components
    438  * @uses bp_get_option() To get the blog/forum comments option
    439  * @return bool Is blog/forum comments allowed?
     453 * @since BuddyPress (1.6.0)
     454 *
     455 * @todo split and move into blog and forum components.
     456 * @uses bp_get_option() To get the blog/forum comments option.
     457 *
     458 * @param bool $default Optional. Fallback value if not found in the database.
     459 *        Default: false.
     460 * @return bool True if activity comments are disabled for blog and forum
     461 *         items, otherwise false.
    440462 */
    441463function bp_disable_blogforum_comments( $default = false ) {
    … …  
    446468 * Is group creation turned off?
    447469 *
    448  * @since BuddyPress (1.6)
    449  *
    450  * @param bool $default Optional. Default value true
    451  *
    452  * @todo Move into groups component
    453  * @uses bp_get_option() To get the group creation
    454  * @return bool Allow group creation?
     470 * @since BuddyPress (1.6.0)
     471 *
     472 * @todo Move into groups component.
     473 * @uses bp_get_option() To get the group creation.
     474 *
     475 * @param bool $default Optional. Fallback value if not found in the database.
     476 *        Default: true.
     477 * @return bool True if group creation is restricted, otherwise false.
    455478 */
    456479function bp_restrict_group_creation( $default = true ) {
    … …  
    459482
    460483/**
    461  * Have we migrated to using the WordPress Toolbar?
    462  *
    463  * @since BuddyPress (1.6)
    464  *
    465  * @param bool $default Optional. Default value true
    466  *
    467  * @todo Move into groups component
    468  * @uses bp_get_option() To get the WP editor option
    469  * @return bool Use WP editor?
     484 * Should the old BuddyBar be forced in place of the WP admin bar?
     485 *
     486 * @since BuddyPress (1.6.0)
     487 *
     488 * @uses bp_get_option() To get the BuddyBar option.
     489 *
     490 * @param bool $default Optional. Fallback value if not found in the database.
     491 *        Default: true.
     492 * @return bool True if the BuddyBar should be forced on, otherwise false.
    470493 */
    471494function bp_force_buddybar( $default = true ) {
    … …  
    474497
    475498/**
    476  * Output the group forums root parent forum id
    477  *
    478  * @since BuddyPress (1.6)
    479  *
    480  * @param bool $default Optional. Default value
     499 * Output the group forums root parent forum id.
     500 *
     501 * @since BuddyPress (1.6.0)
     502 *
     503 * @param bool $default Optional. Default: '0'.
    481504 */
    482505function bp_group_forums_root_id( $default = '0' ) {
    … …  
    484507}
    485508    /**
    486      * Return the group forums root parent forum id
     509     * Return the group forums root parent forum id.
    487510     *
    488      * @since BuddyPress (1.6)
     511     * @since BuddyPress (1.6.0)
    489512     *
    490      * @param bool $default Optional. Default value 0
     513     * @uses bp_get_option() To get the root forum ID from the database.
    491514     *
    492      * @uses bp_get_option() To get the maximum title length
    493      * @return int Is anonymous posting allowed?
     515     * @param bool $default Optional. Default: '0'.
     516     * @return int The ID of the group forums root forum.
    494517     */
    495518    function bp_get_group_forums_root_id( $default = '0' ) {
    … …  
    498521
    499522/**
    500  * Checks if BuddyPress Group Forums are enabled
    501  *
    502  * @since BuddyPress (1.6)
    503  *
    504  * @param bool $default Optional. Default value true
    505  *
    506  * @uses bp_get_option() To get the group forums option
    507  * @return bool Is group forums enabled or not
     523 * Check whether BuddyPress Group Forums are enabled.
     524 *
     525 * @since BuddyPress (1.6.0)
     526 *
     527 * @uses bp_get_option() To get the group forums option.
     528 *
     529 * @param bool $default Optional. Fallback value if not found in the database.
     530 *        Default: true.
     531 * @return bool True if group forums are active, otherwise false.
    508532 */
    509533function bp_is_group_forums_active( $default = true ) {
    … …  
    512536
    513537/**
    514  * Checks if Akismet is enabled
    515  *
    516  * @since BuddyPress (1.6)
    517  *
    518  * @param bool $default Optional. Default value true
    519  *
    520  * @uses bp_get_option() To get the Akismet option
    521  * @return bool Is Akismet enabled or not
     538 * Check whether Akismet is enabled.
     539 *
     540 * @since BuddyPress (1.6.0)
     541 *
     542 * @uses bp_get_option() To get the Akismet option.
     543 *
     544 * @param bool $default Optional. Fallback value if not found in the database.
     545 *        Default: true.
     546 * @return bool True if Akismet is enabled, otherwise false.
    522547 */
    523548function bp_is_akismet_active( $default = true ) {
    … …  
    526551
    527552/**
    528  * Get the current theme package ID
    529  *
    530  * @since BuddyPress (1.7)
    531  *
    532  * @param string $default Optional. Default value 'default'
    533  * @uses get_option() To get the subtheme option
    534  * @return string ID of the subtheme
     553 * Get the current theme package ID.
     554 *
     555 * @since BuddyPress (1.7.0)
     556 *
     557 * @uses get_option() To get the theme package option.
     558 *
     559 * @param bool $default Optional. Fallback value if not found in the database.
     560 *        Default: 'legacy'.
     561 * @return string ID of the theme package.
    535562 */
    536563function bp_get_theme_package_id( $default = 'legacy' ) {
Note: See TracChangeset for help on using the changeset viewer.