Index: /trunk/bp-core/bp-core-cssjs.php
===================================================================
--- /trunk/bp-core/bp-core-cssjs.php	(revision 7445)
+++ /trunk/bp-core/bp-core-cssjs.php	(revision 7446)
@@ -1,5 +1,5 @@
 <?php
 /**
- * Core component CSS & JS
+ * Core component CSS & JS.
  *
  * @package BuddyPress
@@ -10,4 +10,7 @@
 if ( !defined( 'ABSPATH' ) ) exit;
 
+/**
+ * Load the JS for "Are you sure?" .confirm links.
+ */
 function bp_core_confirmation_js() {
 
@@ -36,9 +39,5 @@
 
 /**
- * bp_core_add_jquery_cropper()
- *
- * Makes sure the jQuery jCrop library is loaded.
- *
- * @package BuddyPress Core
+ * Enqueues jCrop library and hooks BP's custom cropper JS.
  */
 function bp_core_add_jquery_cropper() {
@@ -50,9 +49,5 @@
 
 /**
- * bp_core_add_cropper_inline_js()
- *
- * Adds the inline JS needed for the cropper to work on a per-page basis.
- *
- * @package BuddyPress Core
+ * Output the inline JS needed for the cropper to work on a per-page basis.
  */
 function bp_core_add_cropper_inline_js() {
@@ -120,7 +115,5 @@
 
 /**
- * bp_core_add_cropper_inline_css()
- *
- * Adds the inline CSS needed for the cropper to work on a per-page basis.
+ * Output the inline CSS for the BP image cropper.
  *
  * @package BuddyPress Core
@@ -144,7 +137,7 @@
 
 /**
- * Adds AJAX target URL so themes can access the WordPress AJAX functionality.
+ * Define the 'ajaxurl' JS variable, used by themes as an AJAX endpoint.
  *
- * @since BuddyPress (1.1)
+ * @since BuddyPress (1.1.0)
  */
 function bp_core_add_ajax_url_js() {
@@ -158,12 +151,12 @@
 
 /**
- * Returns the proper value for BP's ajaxurl
+ * Get the proper value for BP's ajaxurl.
  *
  * Designed to be sensitive to FORCE_SSL_ADMIN and non-standard multisite
  * configurations.
  *
- * @since BuddyPress (1.7)
+ * @since BuddyPress (1.7.0)
  *
- * @return string
+ * @return string AJAX endpoint URL.
  */
 function bp_core_ajax_url() {
Index: /trunk/bp-core/bp-core-dependency.php
===================================================================
--- /trunk/bp-core/bp-core-dependency.php	(revision 7445)
+++ /trunk/bp-core/bp-core-dependency.php	(revision 7446)
@@ -2,5 +2,5 @@
 
 /**
- * Plugin Dependency
+ * Plugin Dependency Action Hooks.
  *
  * The purpose of the following hooks is to mimic the behavior of something
@@ -8,9 +8,9 @@
  * own in a safe and reliable way.
  *
- * We do this in BuddyPress by mirroring existing WordPress hookss in many places
+ * We do this in BuddyPress by mirroring existing WordPress hooks in many places
  * allowing dependant plugins to hook into the BuddyPress specific ones, thus
  * guaranteeing proper code execution only when BuddyPress is active.
  *
- * The following functions are wrappers for hookss, allowing them to be
+ * The following functions are wrappers for hooks, allowing them to be
  * manually called and/or piggy-backed on top of other hooks if needed.
  *
@@ -19,5 +19,5 @@
 
 /**
- * Include files on this action
+ * Fire the 'bp_include' action, where plugins should include files.
  */
 function bp_include() {
@@ -26,5 +26,5 @@
 
 /**
- * Include files on this action
+ * Fire the 'bp_setup_components' action, where plugins should initialize components.
  */
 function bp_setup_components() {
@@ -33,5 +33,5 @@
 
 /**
- * Setup global variables and objects
+ * Fire the 'bp_setup_globals' action, where plugins should initialize global settings.
  */
 function bp_setup_globals() {
@@ -40,5 +40,5 @@
 
 /**
- * Set navigation elements
+ * Fire the 'bp_setup_nav' action, where plugins should register their navigation items.
  */
 function bp_setup_nav() {
@@ -47,5 +47,5 @@
 
 /**
- * Set up BuddyPress implementation of the WP Toolbar
+ * Fire the 'bp_setup_admin_bar' action, where plugins should add items to the WP admin bar.
  */
 function bp_setup_admin_bar() {
@@ -55,5 +55,5 @@
 
 /**
- * Set the page title
+ * Fire the 'bp_setup_title' action, where plugins should modify the page title.
  */
 function bp_setup_title() {
@@ -62,5 +62,5 @@
 
 /**
- * Register widgets
+ * Fire the 'bp_register_widgets' action, where plugins should register widgets.
  */
 function bp_setup_widgets() {
@@ -69,8 +69,8 @@
 
 /**
- * Setup the currently logged-in user
- *
- * @uses did_action() To make sure the user isn't loaded out of order
- * @uses do_action() Calls 'bp_setup_current_user'
+ * Set up the currently logged-in user.
+ *
+ * @uses did_action() To make sure the user isn't loaded out of order.
+ * @uses do_action() Calls 'bp_setup_current_user'.
  */
 function bp_setup_current_user() {
@@ -86,5 +86,5 @@
 
 /**
- * Initlialize code
+ * Fire the 'bp_init' action, BuddyPress's main initialization hook.
  */
 function bp_init() {
@@ -93,5 +93,7 @@
 
 /**
- * Attached to plugins_loaded
+ * Fire the 'bp_loaded' action, which fires after BP's core plugin files have been loaded.
+ *
+ * Attached to 'plugins_loaded'.
  */
 function bp_loaded() {
@@ -100,5 +102,7 @@
 
 /**
- * Attached to wp
+ * Fire the 'bp_ready' action, which runs after BP is set up and the page is about to render.
+ *
+ * Attached to 'wp'.
  */
 function bp_ready() {
@@ -107,5 +111,8 @@
 
 /**
- * Attach potential template actions
+ * Fire the 'bp_actions' action, which runs just before rendering.
+ *
+ * Attach potential template actions, such as catching form requests or routing
+ * custom URLs.
  */
 function bp_actions() {
@@ -114,5 +121,8 @@
 
 /**
- * Attach potential template screens
+ * Fire the 'bp_screens' action, which runs just before rendering.
+ *
+ * Runs just after 'bp_actions'. Use this hook to attach your template
+ * loaders.
  */
 function bp_screens() {
@@ -121,5 +131,7 @@
 
 /**
- * Initialize widgets
+ * Fire 'bp_widgets_init', which runs after widgets have been set up.
+ *
+ * Hooked to 'widgets_init'.
  */
 function bp_widgets_init() {
@@ -128,5 +140,7 @@
 
 /**
- * BuddyPress head scripts
+ * Fire 'bp_head', which is used to hook scripts and styles in the <head>.
+ *
+ * Hooked to 'wp_head'.
  */
 function bp_head() {
@@ -137,8 +151,11 @@
 
 /**
- * The main action used for redirecting BuddyPress theme actions that are not
- * permitted by the current_user
- *
- * @since BuddyPress (1.6)
+ * Fire the 'bp_template_redirect' action.
+ *
+ * Run at 'template_redirect', just before WordPress selects and loads a theme
+ * template. The main purpose of this hook in BuddyPress is to redirect users
+ * who do not have the proper permission to access certain content.
+ *
+ * @since BuddyPress (1.6.0)
  *
  * @uses do_action()
@@ -151,7 +168,10 @@
 
 /**
- * The main action used registering theme directory
- *
- * @since BuddyPress (1.5)
+ * Fire the 'bp_register_theme_directory' action.
+ *
+ * The main action used registering theme directories.
+ *
+ * @since BuddyPress (1.5.0)
+ *
  * @uses do_action()
  */
@@ -161,7 +181,10 @@
 
 /**
- * The main action used registering theme packages
- *
- * @since BuddyPress (1.7)
+ * Fire the 'bp_register_theme_packages' action.
+ *
+ * The main action used registering theme packages.
+ *
+ * @since BuddyPress (1.7.0)
+ *
  * @uses do_action()
  */
@@ -171,9 +194,9 @@
 
 /**
- * Enqueue BuddyPress specific CSS and JS
- *
- * @since BuddyPress (1.6)
- *
- * @uses do_action() Calls 'bp_enqueue_scripts'
+ * Fire the 'bp_enqueue_scripts' action, where BP enqueues its CSS and JS.
+ *
+ * @since BuddyPress (1.6.0)
+ *
+ * @uses do_action() Calls 'bp_enqueue_scripts'.
  */
 function bp_enqueue_scripts() {
@@ -182,8 +205,9 @@
 
 /**
- * Add the BuddyPress-specific rewrite tags
- *
- * @since BuddyPress (1.8)
- * @uses do_action() Calls 'bp_add_rewrite_tags'
+ * Fire the 'bp_add_rewrite_tag' action, where BP adds its custom rewrite tags.
+ *
+ * @since BuddyPress (1.8.0)
+ *
+ * @uses do_action() Calls 'bp_add_rewrite_tags'.
  */
 function bp_add_rewrite_tags() {
@@ -192,8 +216,9 @@
 
 /**
- * Add the BuddyPress-specific rewrite rules
- *
- * @since BuddyPress (1.9)
- * @uses do_action() Calls 'bp_add_rewrite_rules'
+ * Fire the 'bp_add_rewrite_rules' action, where BP adds its custom rewrite rules.
+ *
+ * @since BuddyPress (1.9.0)
+ *
+ * @uses do_action() Calls 'bp_add_rewrite_rules'.
  */
 function bp_add_rewrite_rules() {
@@ -202,8 +227,9 @@
 
 /**
- * Add the BuddyPress-specific permalink structures
- *
- * @since BuddyPress (1.9)
- * @uses do_action() Calls 'bp_add_permastructs'
+ * Fire the 'bp_add_permastructs' action, where BP adds its BP-specific permalink structure.
+ *
+ * @since BuddyPress (1.9.0)
+ *
+ * @uses do_action() Calls 'bp_add_permastructs'.
  */
 function bp_add_permastructs() {
@@ -212,10 +238,12 @@
 
 /**
- * Piggy back action for BuddyPress sepecific theme actions before the theme has
- * been setup and the theme's functions.php has loaded.
- *
- * @since BuddyPress (1.6)
- *
- * @uses do_action() Calls 'bp_setup_theme'
+ * Fire the 'bp_setup_theme' action.
+ *
+ * The main purpose of 'bp_setup_theme' is give themes a place to load their
+ * BuddyPress-specific functionality.
+ *
+ * @since BuddyPress (1.6.0)
+ *
+ * @uses do_action() Calls 'bp_setup_theme'.
  */
 function bp_setup_theme() {
@@ -224,6 +252,8 @@
 
 /**
- * Piggy back action for BuddyPress sepecific theme actions once the theme has
- * been setup and the theme's functions.php has loaded.
+ * Fire the 'bp_after_setup_theme' action.
+ *
+ * Piggy-back action for BuddyPress-specific theme actions once the theme has
+ * been set up and the theme's functions.php has loaded.
  *
  * Hooked to 'after_setup_theme' with a priority of 100. This allows plenty of
@@ -231,7 +261,7 @@
  * before our theme compatibility layer kicks in.
  *
- * @since BuddyPress (1.6)
- *
- * @uses do_action() Calls 'bp_after_setup_theme'
+ * @since BuddyPress (1.6.0)
+ *
+ * @uses do_action() Calls 'bp_after_setup_theme'.
  */
 function bp_after_setup_theme() {
@@ -242,9 +272,12 @@
 
 /**
- * Piggy back filter for WordPress's 'request' filter
- *
- * @since BuddyPress (1.7)
- * @param array $query_vars
- * @return array
+ * Fire the 'bp_request' filter, a piggy-back of WP's 'request'.
+ *
+ * @since BuddyPress (1.7.0)
+ *
+ * @see WP::parse_request() for a description of parameters.
+ *
+ * @param array $query_vars See {@link WP::parse_request()}.
+ * @return array $query_vars See {@link WP::parse_request()}.
  */
 function bp_request( $query_vars = array() ) {
@@ -253,11 +286,11 @@
 
 /**
- * Piggy back filter to handle login redirects.
- *
- * @since BuddyPress (1.7)
- *
- * @param string $redirect_to
- * @param string $redirect_to_raw
- * @param string $user
+ * Fire the 'bp_login_redirect' filter, a piggy-back of WP's 'login_redirect'.
+ *
+ * @since BuddyPress (1.7.0)
+ *
+ * @param string $redirect_to See 'login_redirect'.
+ * @param string $redirect_to_raw See 'login_redirect'.
+ * @param string $user See 'login_redirect'.
  */
 function bp_login_redirect( $redirect_to = '', $redirect_to_raw = '', $user = false ) {
@@ -266,13 +299,14 @@
 
 /**
- * The main filter used for theme compatibility and displaying custom BuddyPress
- * theme files.
- *
- * @since BuddyPress (1.6)
+ * Fire 'bp_template_include', main filter used for theme compatibility and displaying custom BP theme files.
+ *
+ * Hooked to 'template_include'.
+ *
+ * @since BuddyPress (1.6.0)
  *
  * @uses apply_filters()
  *
- * @param string $template
- * @return string Template file to use
+ * @param string $template See 'template_include'.
+ * @return string Template file to use.
  */
 function bp_template_include( $template = '' ) {
@@ -281,9 +315,11 @@
 
 /**
- * Generate BuddyPress-specific rewrite rules
- *
- * @since BuddyPress (1.7)
- * @param WP_Rewrite $wp_rewrite
- * @uses do_action() Calls 'bp_generate_rewrite_rules' with {@link WP_Rewrite}
+ * Fire the 'bp_generate_rewrite_rules' filter, where BP generates its rewrite rules.
+ *
+ * @since BuddyPress (1.7.0)
+ *
+ * @uses do_action() Calls 'bp_generate_rewrite_rules' with {@link WP_Rewrite}.
+ *
+ * @param WP_Rewrite $wp_rewrite See 'generate_rewrite_rules'.
  */
 function bp_generate_rewrite_rules( $wp_rewrite ) {
@@ -292,8 +328,11 @@
 
 /**
- * Filter the allowed themes list for BuddyPress specific themes
- *
- * @since BuddyPress (1.7)
- * @uses apply_filters() Calls 'bp_allowed_themes' with the allowed themes list
+ * Fire the 'bp_allowed_themes' filter.
+ *
+ * Filter the allowed themes list for BuddyPress-specific themes.
+ *
+ * @since BuddyPress (1.7.0)
+ *
+ * @uses apply_filters() Calls 'bp_allowed_themes' with the allowed themes list.
  */
 function bp_allowed_themes( $themes ) {
Index: /trunk/bp-core/bp-core-filters.php
===================================================================
--- /trunk/bp-core/bp-core-filters.php	(revision 7445)
+++ /trunk/bp-core/bp-core-filters.php	(revision 7446)
@@ -2,11 +2,11 @@
 
 /**
- * BuddyPress Filters
- *
- * This file contains the filters that are used through-out BuddyPress. They are
+ * BuddyPress Filters.
+ *
+ * This file contains the filters that are used throughout BuddyPress. They are
  * consolidated here to make searching for them easier, and to help developers
  * understand at a glance the order in which things occur.
  *
- * There are a few common places that additional filters can currently be found
+ * There are a few common places that additional filters can currently be found.
  *
  *  - BuddyPress: In {@link BuddyPress::setup_actions()} in buddypress.php
@@ -25,5 +25,5 @@
 
 /**
- * Attach BuddyPress to WordPress
+ * Attach BuddyPress to WordPress.
  *
  * BuddyPress uses its own internal actions to help aid in third-party plugin
@@ -54,5 +54,5 @@
 
 /**
- * Template Compatibility
+ * Template Compatibility.
  *
  * If you want to completely bypass this and manage your own custom BuddyPress
@@ -70,11 +70,11 @@
 
 /**
- * bp_core_exclude_pages()
- *
- * Excludes specific pages from showing on page listings, for example the "Activation" page.
- *
- * @package BuddyPress Core
+ * Prevent specific pages (eg 'Activate') from showing on page listings.
+ *
  * @uses bp_is_active() checks if a BuddyPress component is active.
- * @return array The list of page ID's to exclude
+ *
+ * @param array $pages List of excluded page IDs, as passed to the
+ *        'wp_list_pages_excludes' filter.
+ * @return array The exclude list, with BP's pages added.
  */
 function bp_core_exclude_pages( $pages = array() ) {
@@ -100,11 +100,9 @@
 
 /**
- * bp_core_email_from_name_filter()
- *
- * Sets the "From" name in emails sent to the name of the site and not "WordPress"
- *
- * @package BuddyPress Core
- * @uses bp_get_option() fetches the value for a meta_key in the wp_X_options table
- * @return string The blog name for the root blog
+ * Set "From" name in outgoing email to the site name.
+ *
+ * @uses bp_get_option() fetches the value for a meta_key in the wp_X_options table.
+ *
+ * @return string The blog name for the root blog.
  */
 function bp_core_email_from_name_filter() {
@@ -114,9 +112,9 @@
 
 /**
- * bp_core_filter_comments()
- *
  * Filter the blog post comments array and insert BuddyPress URLs for users.
  *
- * @package BuddyPress Core
+ * @param array $comments The array of comments supplied to the comments template.
+ * @param int $post->ID The post ID.
+ * @return array $comments The modified comment array.
  */
 function bp_core_filter_comments( $comments, $post_id ) {
@@ -151,15 +149,15 @@
 
 /**
- * When a user logs in, redirect him in a logical way
- *
- * @package BuddyPress Core
- *
- * @uses apply_filters Filter bp_core_login_redirect to modify where users are redirected to on
- *   login
- * @param string $redirect_to The URL to be redirected to, sanitized in wp-login.php
+ * When a user logs in, redirect him in a logical way.
+ *
+ * @uses apply_filters() Filter 'bp_core_login_redirect' to modify where users
+ *       are redirected to on login.
+ *
+ * @param string $redirect_to The URL to be redirected to, sanitized
+ *        in wp-login.php.
  * @param string $redirect_to_raw The unsanitized redirect_to URL ($_REQUEST['redirect_to'])
- * @param WP_User $user The WP_User object corresponding to a successfully logged-in user. Otherwise
- *   a WP_Error object
- * @return string The redirect URL
+ * @param WP_User $user The WP_User object corresponding to a successfully
+ *        logged-in user. Otherwise a WP_Error object.
+ * @return string The redirect URL.
  */
 function bp_core_login_redirect( $redirect_to, $redirect_to_raw, $user ) {
@@ -196,13 +194,16 @@
 add_filter( 'bp_login_redirect', 'bp_core_login_redirect', 10, 3 );
 
-/***
- * bp_core_filter_user_welcome_email()
- *
- * Replace the generated password in the welcome email.
- * This will not filter when the site admin registers a user.
- *
- * @uses locate_template To see if custom registration files exist
- * @param string $welcome_email Complete email passed through WordPress
- * @return string Filtered $welcome_email with 'PASSWORD' replaced by [User Set]
+/**
+ * Replace the generated password in the welcome email with '[User Set]'.
+ *
+ * On a standard BP installation, users who register themselves also set their
+ * own passwords. Therefore there is no need for the insecure practice of
+ * emailing the plaintext password to the user in the welcome email.
+ *
+ * This filter will not fire when a user is registered by the site admin.
+ *
+ * @param string $welcome_email Complete email passed through WordPress.
+ * @return string Filtered $welcome_email with the password replaced
+ *         by '[User Set]'.
  */
 function bp_core_filter_user_welcome_email( $welcome_email ) {
@@ -217,16 +218,18 @@
 add_filter( 'update_welcome_user_email', 'bp_core_filter_user_welcome_email' );
 
-/***
- * bp_core_filter_blog_welcome_email()
- *
- * Replace the generated password in the welcome email.
- * This will not filter when the site admin registers a user.
- *
- * @uses locate_template To see if custom registration files exist
- * @param string $welcome_email Complete email passed through WordPress
- * @param integer $blog_id ID of the blog user is joining
- * @param integer $user_id ID of the user joining
- * @param string $password Password of user
- * @return string Filtered $welcome_email with $password replaced by [User Set]
+/**
+ * Replace the generated password in the welcome email with '[User Set]'.
+ *
+ * On a standard BP installation, users who register themselves also set their
+ * own passwords. Therefore there is no need for the insecure practice of
+ * emailing the plaintext password to the user in the welcome email.
+ *
+ * This filter will not fire when a user is registered by the site admin.
+ *
+ * @param string $welcome_email Complete email passed through WordPress.
+ * @param int $blog_id ID of the blog user is joining.
+ * @param int $user_id ID of the user joining.
+ * @param string $password Password of user.
+ * @return string Filtered $welcome_email with $password replaced by '[User Set]'.
  */
 function bp_core_filter_blog_welcome_email( $welcome_email, $blog_id, $user_id, $password ) {
@@ -241,5 +244,22 @@
 add_filter( 'update_welcome_email', 'bp_core_filter_blog_welcome_email', 10, 4 );
 
-// Notify user of signup success.
+/**
+ * Notify new users of a successful registration (with blog).
+ *
+ * This function filter's WP's 'wpmu_signup_blog_notification', and replaces
+ * WP's default welcome email with a BuddyPress-specific message.
+ *
+ * @see wpmu_signup_blog_notification() for a description of parameters.
+ *
+ * @param string $domain The new blog domain.
+ * @param string $path The new blog path.
+ * @param string $title The site title.
+ * @param string $user The user's login name.
+ * @param string $user_email The user's email address.
+ * @param string $key The activation key created in wpmu_signup_blog()
+ * @param array $meta By default, contains the requested privacy setting and
+ *        lang_id.
+ * @return bool True on success, false on failure.
+ */
 function bp_core_activation_signup_blog_notification( $domain, $path, $title, $user, $user_email, $key, $meta ) {
 
@@ -272,4 +292,15 @@
 add_filter( 'wpmu_signup_blog_notification', 'bp_core_activation_signup_blog_notification', 1, 7 );
 
+/**
+ * Notify new users of a successful registration (without blog).
+ *
+ * @see wpmu_signup_user_notification() for a full description of params.
+ *
+ * @param string $user The user's login name.
+ * @param string $user_email The user's email address.
+ * @param string $key The activation key created in wpmu_signup_user()
+ * @param array $meta By default, an empty array.
+ * @return bool True on success, false on failure.
+ */
 function bp_core_activation_signup_user_notification( $user, $user_email, $key, $meta ) {
 
@@ -301,13 +332,15 @@
 
 /**
- * Filter the page title for BuddyPress pages
- *
- * @global object $bp BuddyPress global settings
- * @param string $title Original page title
+ * Filter the page title for BuddyPress pages.
+ *
+ * @since BuddyPress (1.5.0)
+ *
+ * @see wp_title()
+ * @global object $bp BuddyPress global settings.
+ *
+ * @param string $title Original page title.
  * @param string $sep How to separate the various items within the page title.
- * @param string $seplocation Direction to display title
- * @return string new page title
- * @see wp_title()
- * @since BuddyPress (1.5)
+ * @param string $seplocation Direction to display title.
+ * @return string New page title.
  */
 function bp_modify_page_title( $title, $sep, $seplocation ) {
