Skip to:
Content

BuddyPress.org

Changeset 7446


Ignore:
Timestamp:
10/19/2013 06:41:17 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-cssjs.php

    r7298 r7446  
    11<?php
    22/**
    3  * Core component CSS & JS
     3 * Core component CSS & JS.
    44 *
    55 * @package BuddyPress
    … …  
    1010if ( !defined( 'ABSPATH' ) ) exit;
    1111
     12/**
     13 * Load the JS for "Are you sure?" .confirm links.
     14 */
    1215function bp_core_confirmation_js() {
    1316
    … …  
    3639
    3740/**
    38  * bp_core_add_jquery_cropper()
    39  *
    40  * Makes sure the jQuery jCrop library is loaded.
    41  *
    42  * @package BuddyPress Core
     41 * Enqueues jCrop library and hooks BP's custom cropper JS.
    4342 */
    4443function bp_core_add_jquery_cropper() {
    … …  
    5049
    5150/**
    52  * bp_core_add_cropper_inline_js()
    53  *
    54  * Adds the inline JS needed for the cropper to work on a per-page basis.
    55  *
    56  * @package BuddyPress Core
     51 * Output the inline JS needed for the cropper to work on a per-page basis.
    5752 */
    5853function bp_core_add_cropper_inline_js() {
    … …  
    120115
    121116/**
    122  * bp_core_add_cropper_inline_css()
    123  *
    124  * Adds the inline CSS needed for the cropper to work on a per-page basis.
     117 * Output the inline CSS for the BP image cropper.
    125118 *
    126119 * @package BuddyPress Core
    … …  
    144137
    145138/**
    146  * Adds AJAX target URL so themes can access the WordPress AJAX functionality.
     139 * Define the 'ajaxurl' JS variable, used by themes as an AJAX endpoint.
    147140 *
    148  * @since BuddyPress (1.1)
     141 * @since BuddyPress (1.1.0)
    149142 */
    150143function bp_core_add_ajax_url_js() {
    … …  
    158151
    159152/**
    160  * Returns the proper value for BP's ajaxurl
     153 * Get the proper value for BP's ajaxurl.
    161154 *
    162155 * Designed to be sensitive to FORCE_SSL_ADMIN and non-standard multisite
    163156 * configurations.
    164157 *
    165  * @since BuddyPress (1.7)
     158 * @since BuddyPress (1.7.0)
    166159 *
    167  * @return string
     160 * @return string AJAX endpoint URL.
    168161 */
    169162function bp_core_ajax_url() {

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

    r7367 r7446  
    22
    33/**
    4  * Plugin Dependency
     4 * Plugin Dependency Action Hooks.
    55 *
    66 * The purpose of the following hooks is to mimic the behavior of something
    … …  
    88 * own in a safe and reliable way.
    99 *
    10  * We do this in BuddyPress by mirroring existing WordPress hookss in many places
     10 * We do this in BuddyPress by mirroring existing WordPress hooks in many places
    1111 * allowing dependant plugins to hook into the BuddyPress specific ones, thus
    1212 * guaranteeing proper code execution only when BuddyPress is active.
    1313 *
    14  * The following functions are wrappers for hookss, allowing them to be
     14 * The following functions are wrappers for hooks, allowing them to be
    1515 * manually called and/or piggy-backed on top of other hooks if needed.
    1616 *
    … …  
    1919
    2020/**
    21  * Include files on this action
     21 * Fire the 'bp_include' action, where plugins should include files.
    2222 */
    2323function bp_include() {
    … …  
    2626
    2727/**
    28  * Include files on this action
     28 * Fire the 'bp_setup_components' action, where plugins should initialize components.
    2929 */
    3030function bp_setup_components() {
    … …  
    3333
    3434/**
    35  * Setup global variables and objects
     35 * Fire the 'bp_setup_globals' action, where plugins should initialize global settings.
    3636 */
    3737function bp_setup_globals() {
    … …  
    4040
    4141/**
    42  * Set navigation elements
     42 * Fire the 'bp_setup_nav' action, where plugins should register their navigation items.
    4343 */
    4444function bp_setup_nav() {
    … …  
    4747
    4848/**
    49  * Set up BuddyPress implementation of the WP Toolbar
     49 * Fire the 'bp_setup_admin_bar' action, where plugins should add items to the WP admin bar.
    5050 */
    5151function bp_setup_admin_bar() {
    … …  
    5555
    5656/**
    57  * Set the page title
     57 * Fire the 'bp_setup_title' action, where plugins should modify the page title.
    5858 */
    5959function bp_setup_title() {
    … …  
    6262
    6363/**
    64  * Register widgets
     64 * Fire the 'bp_register_widgets' action, where plugins should register widgets.
    6565 */
    6666function bp_setup_widgets() {
    … …  
    6969
    7070/**
    71  * Setup the currently logged-in user
    72  *
    73  * @uses did_action() To make sure the user isn't loaded out of order
    74  * @uses do_action() Calls 'bp_setup_current_user'
     71 * Set up the currently logged-in user.
     72 *
     73 * @uses did_action() To make sure the user isn't loaded out of order.
     74 * @uses do_action() Calls 'bp_setup_current_user'.
    7575 */
    7676function bp_setup_current_user() {
    … …  
    8686
    8787/**
    88  * Initlialize code
     88 * Fire the 'bp_init' action, BuddyPress's main initialization hook.
    8989 */
    9090function bp_init() {
    … …  
    9393
    9494/**
    95  * Attached to plugins_loaded
     95 * Fire the 'bp_loaded' action, which fires after BP's core plugin files have been loaded.
     96 *
     97 * Attached to 'plugins_loaded'.
    9698 */
    9799function bp_loaded() {
    … …  
    100102
    101103/**
    102  * Attached to wp
     104 * Fire the 'bp_ready' action, which runs after BP is set up and the page is about to render.
     105 *
     106 * Attached to 'wp'.
    103107 */
    104108function bp_ready() {
    … …  
    107111
    108112/**
    109  * Attach potential template actions
     113 * Fire the 'bp_actions' action, which runs just before rendering.
     114 *
     115 * Attach potential template actions, such as catching form requests or routing
     116 * custom URLs.
    110117 */
    111118function bp_actions() {
    … …  
    114121
    115122/**
    116  * Attach potential template screens
     123 * Fire the 'bp_screens' action, which runs just before rendering.
     124 *
     125 * Runs just after 'bp_actions'. Use this hook to attach your template
     126 * loaders.
    117127 */
    118128function bp_screens() {
    … …  
    121131
    122132/**
    123  * Initialize widgets
     133 * Fire 'bp_widgets_init', which runs after widgets have been set up.
     134 *
     135 * Hooked to 'widgets_init'.
    124136 */
    125137function bp_widgets_init() {
    … …  
    128140
    129141/**
    130  * BuddyPress head scripts
     142 * Fire 'bp_head', which is used to hook scripts and styles in the <head>.
     143 *
     144 * Hooked to 'wp_head'.
    131145 */
    132146function bp_head() {
    … …  
    137151
    138152/**
    139  * The main action used for redirecting BuddyPress theme actions that are not
    140  * permitted by the current_user
    141  *
    142  * @since BuddyPress (1.6)
     153 * Fire the 'bp_template_redirect' action.
     154 *
     155 * Run at 'template_redirect', just before WordPress selects and loads a theme
     156 * template. The main purpose of this hook in BuddyPress is to redirect users
     157 * who do not have the proper permission to access certain content.
     158 *
     159 * @since BuddyPress (1.6.0)
    143160 *
    144161 * @uses do_action()
    … …  
    151168
    152169/**
    153  * The main action used registering theme directory
    154  *
    155  * @since BuddyPress (1.5)
     170 * Fire the 'bp_register_theme_directory' action.
     171 *
     172 * The main action used registering theme directories.
     173 *
     174 * @since BuddyPress (1.5.0)
     175 *
    156176 * @uses do_action()
    157177 */
    … …  
    161181
    162182/**
    163  * The main action used registering theme packages
    164  *
    165  * @since BuddyPress (1.7)
     183 * Fire the 'bp_register_theme_packages' action.
     184 *
     185 * The main action used registering theme packages.
     186 *
     187 * @since BuddyPress (1.7.0)
     188 *
    166189 * @uses do_action()
    167190 */
    … …  
    171194
    172195/**
    173  * Enqueue BuddyPress specific CSS and JS
    174  *
    175  * @since BuddyPress (1.6)
    176  *
    177  * @uses do_action() Calls 'bp_enqueue_scripts'
     196 * Fire the 'bp_enqueue_scripts' action, where BP enqueues its CSS and JS.
     197 *
     198 * @since BuddyPress (1.6.0)
     199 *
     200 * @uses do_action() Calls 'bp_enqueue_scripts'.
    178201 */
    179202function bp_enqueue_scripts() {
    … …  
    182205
    183206/**
    184  * Add the BuddyPress-specific rewrite tags
    185  *
    186  * @since BuddyPress (1.8)
    187  * @uses do_action() Calls 'bp_add_rewrite_tags'
     207 * Fire the 'bp_add_rewrite_tag' action, where BP adds its custom rewrite tags.
     208 *
     209 * @since BuddyPress (1.8.0)
     210 *
     211 * @uses do_action() Calls 'bp_add_rewrite_tags'.
    188212 */
    189213function bp_add_rewrite_tags() {
    … …  
    192216
    193217/**
    194  * Add the BuddyPress-specific rewrite rules
    195  *
    196  * @since BuddyPress (1.9)
    197  * @uses do_action() Calls 'bp_add_rewrite_rules'
     218 * Fire the 'bp_add_rewrite_rules' action, where BP adds its custom rewrite rules.
     219 *
     220 * @since BuddyPress (1.9.0)
     221 *
     222 * @uses do_action() Calls 'bp_add_rewrite_rules'.
    198223 */
    199224function bp_add_rewrite_rules() {
    … …  
    202227
    203228/**
    204  * Add the BuddyPress-specific permalink structures
    205  *
    206  * @since BuddyPress (1.9)
    207  * @uses do_action() Calls 'bp_add_permastructs'
     229 * Fire the 'bp_add_permastructs' action, where BP adds its BP-specific permalink structure.
     230 *
     231 * @since BuddyPress (1.9.0)
     232 *
     233 * @uses do_action() Calls 'bp_add_permastructs'.
    208234 */
    209235function bp_add_permastructs() {
    … …  
    212238
    213239/**
    214  * Piggy back action for BuddyPress sepecific theme actions before the theme has
    215  * been setup and the theme's functions.php has loaded.
    216  *
    217  * @since BuddyPress (1.6)
    218  *
    219  * @uses do_action() Calls 'bp_setup_theme'
     240 * Fire the 'bp_setup_theme' action.
     241 *
     242 * The main purpose of 'bp_setup_theme' is give themes a place to load their
     243 * BuddyPress-specific functionality.
     244 *
     245 * @since BuddyPress (1.6.0)
     246 *
     247 * @uses do_action() Calls 'bp_setup_theme'.
    220248 */
    221249function bp_setup_theme() {
    … …  
    224252
    225253/**
    226  * Piggy back action for BuddyPress sepecific theme actions once the theme has
    227  * been setup and the theme's functions.php has loaded.
     254 * Fire the 'bp_after_setup_theme' action.
     255 *
     256 * Piggy-back action for BuddyPress-specific theme actions once the theme has
     257 * been set up and the theme's functions.php has loaded.
    228258 *
    229259 * Hooked to 'after_setup_theme' with a priority of 100. This allows plenty of
    … …  
    231261 * before our theme compatibility layer kicks in.
    232262 *
    233  * @since BuddyPress (1.6)
    234  *
    235  * @uses do_action() Calls 'bp_after_setup_theme'
     263 * @since BuddyPress (1.6.0)
     264 *
     265 * @uses do_action() Calls 'bp_after_setup_theme'.
    236266 */
    237267function bp_after_setup_theme() {
    … …  
    242272
    243273/**
    244  * Piggy back filter for WordPress's 'request' filter
    245  *
    246  * @since BuddyPress (1.7)
    247  * @param array $query_vars
    248  * @return array
     274 * Fire the 'bp_request' filter, a piggy-back of WP's 'request'.
     275 *
     276 * @since BuddyPress (1.7.0)
     277 *
     278 * @see WP::parse_request() for a description of parameters.
     279 *
     280 * @param array $query_vars See {@link WP::parse_request()}.
     281 * @return array $query_vars See {@link WP::parse_request()}.
    249282 */
    250283function bp_request( $query_vars = array() ) {
    … …  
    253286
    254287/**
    255  * Piggy back filter to handle login redirects.
    256  *
    257  * @since BuddyPress (1.7)
    258  *
    259  * @param string $redirect_to
    260  * @param string $redirect_to_raw
    261  * @param string $user
     288 * Fire the 'bp_login_redirect' filter, a piggy-back of WP's 'login_redirect'.
     289 *
     290 * @since BuddyPress (1.7.0)
     291 *
     292 * @param string $redirect_to See 'login_redirect'.
     293 * @param string $redirect_to_raw See 'login_redirect'.
     294 * @param string $user See 'login_redirect'.
    262295 */
    263296function bp_login_redirect( $redirect_to = '', $redirect_to_raw = '', $user = false ) {
    … …  
    266299
    267300/**
    268  * The main filter used for theme compatibility and displaying custom BuddyPress
    269  * theme files.
    270  *
    271  * @since BuddyPress (1.6)
     301 * Fire 'bp_template_include', main filter used for theme compatibility and displaying custom BP theme files.
     302 *
     303 * Hooked to 'template_include'.
     304 *
     305 * @since BuddyPress (1.6.0)
    272306 *
    273307 * @uses apply_filters()
    274308 *
    275  * @param string $template
    276  * @return string Template file to use
     309 * @param string $template See 'template_include'.
     310 * @return string Template file to use.
    277311 */
    278312function bp_template_include( $template = '' ) {
    … …  
    281315
    282316/**
    283  * Generate BuddyPress-specific rewrite rules
    284  *
    285  * @since BuddyPress (1.7)
    286  * @param WP_Rewrite $wp_rewrite
    287  * @uses do_action() Calls 'bp_generate_rewrite_rules' with {@link WP_Rewrite}
     317 * Fire the 'bp_generate_rewrite_rules' filter, where BP generates its rewrite rules.
     318 *
     319 * @since BuddyPress (1.7.0)
     320 *
     321 * @uses do_action() Calls 'bp_generate_rewrite_rules' with {@link WP_Rewrite}.
     322 *
     323 * @param WP_Rewrite $wp_rewrite See 'generate_rewrite_rules'.
    288324 */
    289325function bp_generate_rewrite_rules( $wp_rewrite ) {
    … …  
    292328
    293329/**
    294  * Filter the allowed themes list for BuddyPress specific themes
    295  *
    296  * @since BuddyPress (1.7)
    297  * @uses apply_filters() Calls 'bp_allowed_themes' with the allowed themes list
     330 * Fire the 'bp_allowed_themes' filter.
     331 *
     332 * Filter the allowed themes list for BuddyPress-specific themes.
     333 *
     334 * @since BuddyPress (1.7.0)
     335 *
     336 * @uses apply_filters() Calls 'bp_allowed_themes' with the allowed themes list.
    298337 */
    299338function bp_allowed_themes( $themes ) {

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

    r7427 r7446  
    22
    33/**
    4  * BuddyPress Filters
    5  *
    6  * This file contains the filters that are used through-out BuddyPress. They are
     4 * BuddyPress Filters.
     5 *
     6 * This file contains the filters that are used throughout BuddyPress. They are
    77 * consolidated here to make searching for them easier, and to help developers
    88 * understand at a glance the order in which things occur.
    99 *
    10  * There are a few common places that additional filters can currently be found
     10 * There are a few common places that additional filters can currently be found.
    1111 *
    1212 *  - BuddyPress: In {@link BuddyPress::setup_actions()} in buddypress.php
    … …  
    2525
    2626/**
    27  * Attach BuddyPress to WordPress
     27 * Attach BuddyPress to WordPress.
    2828 *
    2929 * BuddyPress uses its own internal actions to help aid in third-party plugin
    … …  
    5454
    5555/**
    56  * Template Compatibility
     56 * Template Compatibility.
    5757 *
    5858 * If you want to completely bypass this and manage your own custom BuddyPress
    … …  
    7070
    7171/**
    72  * bp_core_exclude_pages()
    73  *
    74  * Excludes specific pages from showing on page listings, for example the "Activation" page.
    75  *
    76  * @package BuddyPress Core
     72 * Prevent specific pages (eg 'Activate') from showing on page listings.
     73 *
    7774 * @uses bp_is_active() checks if a BuddyPress component is active.
    78  * @return array The list of page ID's to exclude
     75 *
     76 * @param array $pages List of excluded page IDs, as passed to the
     77 *        'wp_list_pages_excludes' filter.
     78 * @return array The exclude list, with BP's pages added.
    7979 */
    8080function bp_core_exclude_pages( $pages = array() ) {
    … …  
    100100
    101101/**
    102  * bp_core_email_from_name_filter()
    103  *
    104  * Sets the "From" name in emails sent to the name of the site and not "WordPress"
    105  *
    106  * @package BuddyPress Core
    107  * @uses bp_get_option() fetches the value for a meta_key in the wp_X_options table
    108  * @return string The blog name for the root blog
     102 * Set "From" name in outgoing email to the site name.
     103 *
     104 * @uses bp_get_option() fetches the value for a meta_key in the wp_X_options table.
     105 *
     106 * @return string The blog name for the root blog.
    109107 */
    110108function bp_core_email_from_name_filter() {
    … …  
    114112
    115113/**
    116  * bp_core_filter_comments()
    117  *
    118114 * Filter the blog post comments array and insert BuddyPress URLs for users.
    119115 *
    120  * @package BuddyPress Core
     116 * @param array $comments The array of comments supplied to the comments template.
     117 * @param int $post->ID The post ID.
     118 * @return array $comments The modified comment array.
    121119 */
    122120function bp_core_filter_comments( $comments, $post_id ) {
    … …  
    151149
    152150/**
    153  * When a user logs in, redirect him in a logical way
    154  *
    155  * @package BuddyPress Core
    156  *
    157  * @uses apply_filters Filter bp_core_login_redirect to modify where users are redirected to on
    158  *   login
    159  * @param string $redirect_to The URL to be redirected to, sanitized in wp-login.php
     151 * When a user logs in, redirect him in a logical way.
     152 *
     153 * @uses apply_filters() Filter 'bp_core_login_redirect' to modify where users
     154 *       are redirected to on login.
     155 *
     156 * @param string $redirect_to The URL to be redirected to, sanitized
     157 *        in wp-login.php.
    160158 * @param string $redirect_to_raw The unsanitized redirect_to URL ($_REQUEST['redirect_to'])
    161  * @param WP_User $user The WP_User object corresponding to a successfully logged-in user. Otherwise
    162  *   a WP_Error object
    163  * @return string The redirect URL
     159 * @param WP_User $user The WP_User object corresponding to a successfully
     160 *        logged-in user. Otherwise a WP_Error object.
     161 * @return string The redirect URL.
    164162 */
    165163function bp_core_login_redirect( $redirect_to, $redirect_to_raw, $user ) {
    … …  
    196194add_filter( 'bp_login_redirect', 'bp_core_login_redirect', 10, 3 );
    197195
    198 /***
    199  * bp_core_filter_user_welcome_email()
    200  *
    201  * Replace the generated password in the welcome email.
    202  * This will not filter when the site admin registers a user.
    203  *
    204  * @uses locate_template To see if custom registration files exist
    205  * @param string $welcome_email Complete email passed through WordPress
    206  * @return string Filtered $welcome_email with 'PASSWORD' replaced by [User Set]
     196/**
     197 * Replace the generated password in the welcome email with '[User Set]'.
     198 *
     199 * On a standard BP installation, users who register themselves also set their
     200 * own passwords. Therefore there is no need for the insecure practice of
     201 * emailing the plaintext password to the user in the welcome email.
     202 *
     203 * This filter will not fire when a user is registered by the site admin.
     204 *
     205 * @param string $welcome_email Complete email passed through WordPress.
     206 * @return string Filtered $welcome_email with the password replaced
     207 *         by '[User Set]'.
    207208 */
    208209function bp_core_filter_user_welcome_email( $welcome_email ) {
    … …  
    217218add_filter( 'update_welcome_user_email', 'bp_core_filter_user_welcome_email' );
    218219
    219 /***
    220  * bp_core_filter_blog_welcome_email()
    221  *
    222  * Replace the generated password in the welcome email.
    223  * This will not filter when the site admin registers a user.
    224  *
    225  * @uses locate_template To see if custom registration files exist
    226  * @param string $welcome_email Complete email passed through WordPress
    227  * @param integer $blog_id ID of the blog user is joining
    228  * @param integer $user_id ID of the user joining
    229  * @param string $password Password of user
    230  * @return string Filtered $welcome_email with $password replaced by [User Set]
     220/**
     221 * Replace the generated password in the welcome email with '[User Set]'.
     222 *
     223 * On a standard BP installation, users who register themselves also set their
     224 * own passwords. Therefore there is no need for the insecure practice of
     225 * emailing the plaintext password to the user in the welcome email.
     226 *
     227 * This filter will not fire when a user is registered by the site admin.
     228 *
     229 * @param string $welcome_email Complete email passed through WordPress.
     230 * @param int $blog_id ID of the blog user is joining.
     231 * @param int $user_id ID of the user joining.
     232 * @param string $password Password of user.
     233 * @return string Filtered $welcome_email with $password replaced by '[User Set]'.
    231234 */
    232235function bp_core_filter_blog_welcome_email( $welcome_email, $blog_id, $user_id, $password ) {
    … …  
    241244add_filter( 'update_welcome_email', 'bp_core_filter_blog_welcome_email', 10, 4 );
    242245
    243 // Notify user of signup success.
     246/**
     247 * Notify new users of a successful registration (with blog).
     248 *
     249 * This function filter's WP's 'wpmu_signup_blog_notification', and replaces
     250 * WP's default welcome email with a BuddyPress-specific message.
     251 *
     252 * @see wpmu_signup_blog_notification() for a description of parameters.
     253 *
     254 * @param string $domain The new blog domain.
     255 * @param string $path The new blog path.
     256 * @param string $title The site title.
     257 * @param string $user The user's login name.
     258 * @param string $user_email The user's email address.
     259 * @param string $key The activation key created in wpmu_signup_blog()
     260 * @param array $meta By default, contains the requested privacy setting and
     261 *        lang_id.
     262 * @return bool True on success, false on failure.
     263 */
    244264function bp_core_activation_signup_blog_notification( $domain, $path, $title, $user, $user_email, $key, $meta ) {
    245265
    … …  
    272292add_filter( 'wpmu_signup_blog_notification', 'bp_core_activation_signup_blog_notification', 1, 7 );
    273293
     294/**
     295 * Notify new users of a successful registration (without blog).
     296 *
     297 * @see wpmu_signup_user_notification() for a full description of params.
     298 *
     299 * @param string $user The user's login name.
     300 * @param string $user_email The user's email address.
     301 * @param string $key The activation key created in wpmu_signup_user()
     302 * @param array $meta By default, an empty array.
     303 * @return bool True on success, false on failure.
     304 */
    274305function bp_core_activation_signup_user_notification( $user, $user_email, $key, $meta ) {
    275306
    … …  
    301332
    302333/**
    303  * Filter the page title for BuddyPress pages
    304  *
    305  * @global object $bp BuddyPress global settings
    306  * @param string $title Original page title
     334 * Filter the page title for BuddyPress pages.
     335 *
     336 * @since BuddyPress (1.5.0)
     337 *
     338 * @see wp_title()
     339 * @global object $bp BuddyPress global settings.
     340 *
     341 * @param string $title Original page title.
    307342 * @param string $sep How to separate the various items within the page title.
    308  * @param string $seplocation Direction to display title
    309  * @return string new page title
    310  * @see wp_title()
    311  * @since BuddyPress (1.5)
     343 * @param string $seplocation Direction to display title.
     344 * @return string New page title.
    312345 */
    313346function bp_modify_page_title( $title, $sep, $seplocation ) {
Note: See TracChangeset for help on using the changeset viewer.