Changeset 7434

Timestamp:

10/16/2013 05:41:34 PM (11 years ago)

Author:

boonebgorges

Message:

Improve inline docs in bp-core. See #5022

Location:

trunk/bp-core

Files:

• bp-core-buddybar.php (modified) (16 diffs)
• bp-core-cache.php (modified) (6 diffs)

trunk/bp-core/bp-core-buddybar.php

@@ -2 +2 @@
 
 /**
- * Core BuddyPress Navigational Functions
+ * Core BuddyPress Navigational Functions.
  *
  * @package BuddyPress
  * @subpackage Core
- * @todo Deprecate BuddyBar functions
+ * @todo Deprecate BuddyBar functions.
  */
 
@@ -13 +13 @@
 
 /**
- * Adds a navigation item to the main navigation array used in BuddyPress themes.
- *
- * @package BuddyPress Core
- * @global BuddyPress $bp The one true BuddyPress instance
+ * Add an item to the main BuddyPress navigation array.
+ *
+ * @global BuddyPress $bp The one true BuddyPress instance.
+ *
+ * @param array $args {
+ *     Array describing the new nav item.
+ *     @type string $name Display name for the nav item.
+ *     @type string $slug Unique URL slug for the nav item.
+ *     @type bool|string $item_css_id Optional. 'id' attribute for the nav
+ *           item. Default: the value of $slug.
+ *     @type bool $show_for_displayed_user Optional. Whether the nav item
+ *           should be visible when viewing a member profile other than your
+ *           own. Default: true.
+ *     @type bool $site_admin_only Optional. Whether the nav item should be
+ *           visible only to site admins (those with the 'bp_moderate' cap).
+ *           Default: false.
+ *     @type int $position Optional. Numerical index specifying where the item
+ *           should appear in the nav array. Default: 99.
+ *     @type callable $screen_function The callback function that will run
+ *           when the nav item is clicked.
+ *     @type bool|string $default_subnav_slug Optional. The slug of the default
+ *           subnav item to select when the nav item is clicked.
+ * }
+ * @return bool|null Returns false on failure.
  */
 function bp_core_new_nav_item( $args = '' ) {
@@ -98 +118 @@
 
 /**
- * Modify the default subnav item to load when a top level nav item is clicked.
- *
- * @package BuddyPress Core
- * @global BuddyPress $bp The one true BuddyPress instance
+ * Modify the default subnav item that loads when a top level nav item is clicked.
+ *
+ * @global BuddyPress $bp The one true BuddyPress instance.
+ *
+ * @param array $args {
+ *     @type string $parent_slug The slug of the nav item whose default is
+ *           being changed.
+ *     @type callable $screen_function The new default callback function that
+ *           will run when the nav item is clicked.
+ *     @type string $subnav_slug The slug of the new default subnav item.
+ * }
  */
 function bp_core_new_nav_default( $args = '' ) {
@@ -164 +191 @@
 
 /**
- * We can only sort nav items by their position integer at a later point in time, once all
- * plugins have registered their navigation items.
- *
- * @package BuddyPress Core
+ * Sort the navigation menu items.
+ *
+ * The sorting is split into a separate function because it can only happen
+ * after all plugins have had a chance to register their navigation items.
+ *
  * @global BuddyPress $bp The one true BuddyPress instance
+ *
+ * @return bool|null Returns false on failure.
  */
 function bp_core_sort_nav_items() {
@@ -198 +228 @@
 
 /**
- * Adds a navigation item to the sub navigation array used in BuddyPress themes.
- *
- * @package BuddyPress Core
- * @global BuddyPress $bp The one true BuddyPress instance
+ * Add a subnav item to the BuddyPress navigation.
+ *
+ * @global BuddyPress $bp The one true BuddyPress instance.
+ *
+ * @param array $args {
+ *     Array describing the new subnav item.
+ *     @type string $name Display name for the subnav item.
+ *     @type string $slug Unique URL slug for the subnav item.
+ *     @type string $parent_slug Slug of the top-level nav item under which the
+ *           new subnav item should be added.
+ *     @type string $parent_url URL of the parent nav item.
+ *     @type bool|string $item_css_id Optional. 'id' attribute for the nav
+ *           item. Default: the value of $slug.
+ *     @type bool $user_has_access Optional. True if the logged-in user has
+ *           access to the subnav item, otherwise false. Can be set dynamically
+ *           when registering the subnav; eg, use bp_is_my_profile() to restrict
+ *           access to profile owners only. Default: true.
+ *     @type bool $site_admin_only Optional. Whether the nav item should be
+ *           visible only to site admins (those with the 'bp_moderate' cap).
+ *           Default: false.
+ *     @type int $position Optional. Numerical index specifying where the item
+ *           should appear in the subnav array. Default: 90.
+ *     @type callable $screen_function The callback function that will run
+ *           when the nav item is clicked.
+ *     @type string $link Optional. The URL that the subnav item should point
+ *           to. Defaults to a value generated from the $parent_url + $slug.
+ * }
+ * @return bool|null Returns false on failure.
  */
 function bp_core_new_subnav_item( $args = '' ) {
@@ -319 +373 @@
 }
 
+/**
+ * Sort all subnavigation arrays.
+ *
+ * @global BuddyPress $bp The one true BuddyPress instance
+ *
+ * @return bool|null Returns false on failure.
+ */
 function bp_core_sort_subnav_items() {
     global $bp;
@@ -350 +411 @@
 
 /**
- * Determines whether a given nav item has subnav items
- *
- * @package BuddyPress
- * @since BuddyPress (1.5)
- *
- * @param string $nav_item The id of the top-level nav item whose nav items you're checking
- * @return bool $has_subnav True if the nav item is found and has subnav items; false otherwise
+ * Check whether a given nav item has subnav items.
+ *
+ * @since BuddyPress (1.5.0)
+ *
+ * @param string $nav_item The slug of the top-level nav item whose subnav
+ *        items you're checking. Default: the current component slug.
+ * @return bool $has_subnav True if the nav item is found and has subnav
+ *        items; false otherwise.
  */
 function bp_nav_item_has_subnav( $nav_item = '' ) {
@@ -370 +432 @@
 
 /**
- * Removes a navigation item from the sub navigation array used in BuddyPress themes.
- *
- * @package BuddyPress Core
- * @param int $parent_id The id of the parent navigation item.
- * @param bool|string false if the parent item doesn't exist or $slug the slug of the sub navigation item.
+ * Remove a nav item from the navigation array.
+ *
+ * @param int $parent_id The slug of the parent navigation item.
+ * @param bool Returns false on failure, ie if the nav item can't be found.
  */
 function bp_core_remove_nav_item( $parent_id ) {
@@ -400 +461 @@
 
 /**
- * Removes a navigation item from the sub navigation array used in BuddyPress themes.
- *
- * @package BuddyPress Core
- * @param string $parent_id The id of the parent navigation item.
- * @param string $slug The slug of the sub navigation item.
+ * Remove a subnav item from the navigation array.
+ *
+ * @param string $parent_id The slug of the parent navigation item.
+ * @param string $slug The slug of the subnav item to be removed.
  */
 function bp_core_remove_subnav_item( $parent_id, $slug ) {
@@ -425 +485 @@
 
 /**
- * Clear the subnav items for a specific nav item.
- *
- * @package BuddyPress Core
- * @param string $parent_id The id of the parent navigation item.
- * @global BuddyPress $bp The one true BuddyPress instance
+ * Clear all subnav items from a specific nav item.
+ *
+ * @global BuddyPress $bp The one true BuddyPress instance.
+ *
+ * @param string $parent_slug The slug of the parent navigation item.
  */
 function bp_core_reset_subnav_items( $parent_slug ) {
@@ -437 +497 @@
 }
 
-/** Template functions ********************************************************/
-
+/** BuddyBar Template functions ***********************************************/
+
+/**
+ * Wrapper function for rendering the BuddyBar.
+ *
+ * @return bool|null Returns false if the BuddyBar is disabled.
+ */
 function bp_core_admin_bar() {
     global $bp;
@@ -466 +531 @@
 }
 
-// **** Default BuddyPress Toolbar logo ********
+/**
+ * Output the BuddyBar logo.
+ */
 function bp_adminbar_logo() {
     echo '<a href="' . bp_get_root_domain() . '" id="admin-bar-logo">' . get_blog_option( bp_get_root_blog_id(), 'blogname' ) . '</a>';
 }
 
-// **** "Log In" and "Sign Up" links (Visible when not logged in) ********
+/**
+ * Output the "Log In" and "Sign Up" names to the BuddyBar.
+ *
+ * Visible only to visitors who are not logged in.
+ *
+ * @return bool|null Returns false if the current user is logged in.
+ */
 function bp_adminbar_login_menu() {
 
@@ -484 +557 @@
 }
 
-
-// **** "My Account" Menu ******
+/**
+ * Output the My Account BuddyBar menu.
+ *
+ * @return bool|null Returns false on failure.
+ */
 function bp_adminbar_account_menu() {
     global $bp;
@@ -558 +634 @@
 }
 
-
-// **** "Random" Menu (visible when not logged in) ********
+/**
+ * Output the Random BuddyBar menu.
+ *
+ * Not visible for logged-in users.
+ */
 function bp_adminbar_random_menu() {
 ?>
@@ -593 +672 @@
  * This is a direct copy of WP's private _get_admin_bar_pref()
  *
- * @since BuddyPress (1.5)
- *
- * @param string $context Context of this preference check, either 'admin' or 'front'.
- * @param int $user Optional. ID of the user to check, defaults to 0 for current user.
+ * @since BuddyPress (1.5.0)
  *
  * @uses get_user_option()
  *
- * @return bool Whether the Toolbar should be showing for this user.
+ * @param string $context Context of this preference check. 'admin' or 'front'.
+ * @param int $user Optional. ID of the user to check. Default: 0 (which falls
+ *        back to the logged-in user's ID).
+ * @return bool True if the toolbar should be showing for this user.
  */
 function bp_get_admin_bar_pref( $context, $user = 0 ) {
@@ -611 +690 @@
 
 /**
- * Handle the BuddyBar CSS
+ * Enqueue the BuddyBar CSS.
  */
 function bp_core_load_buddybar_css() {

trunk/bp-core/bp-core-cache.php

@@ -1 +1 @@
 <?php
 /**
+ * BuddyPress Core Caching Functions.
+ *
  * Caching functions handle the clearing of cached objects and pages on specific
  * actions throughout BuddyPress.
@@ -9 +11 @@
 
 /**
- * REQUIRES WP-SUPER-CACHE
+ * Prune the WP Super Cache.
+ *
+ * @see prune_super_cache()
  *
  * When wp-super-cache is installed this function will clear cached pages
  * so that success/error messages are not cached, or time sensitive content.
- *
- * @package BuddyPress Core
  */
 function bp_core_clear_cache() {
@@ -26 +28 @@
 
 /**
- * Add's 'bp' to global group of network wide cachable objects
- *
- * @package BuddyPress Core
+ * Add 'bp' to global group of network wide cachable objects.
  */
 function bp_core_add_global_group() {
@@ -38 +38 @@
 
 /**
- * Clears all cached objects for a user, or a user is part of.
- *
- * @package BuddyPress Core
+ * Clear all cached objects for a user, or those that a user is part of.
  */
 function bp_core_clear_user_object_cache( $user_id ) {
@@ -47 +45 @@
 
 /**
- * Clears member count caches and transients
+ * Clear member count caches and transients.
  */
 function bp_core_clear_member_count_caches() {
@@ -62 +60 @@
  * Update the metadata cache for the specified objects.
  *
- * @since BuddyPress (1.6)
- * @global $wpdb WordPress database object for queries.
- * @param array $args See $defaults definition for more details
- * @return mixed Metadata cache for the specified objects, or false on failure.
+ * Based on WordPress's {@link update_meta_cache()}, this function primes the
+ * cache with metadata related to a set of objects. This is typically done when
+ * querying for a loop of objects; pre-fetching metadata for each queried
+ * object can lead to dramatic performance improvements when using metadata
+ * in the context of template loops.
+ *
+ * @since BuddyPress (1.6.0)
+ *
+ * @global $wpdb WordPress database object for queries..
+ *
+ * @param array $args {
+ *     Array of arguments.
+ *     @type array|string $object_ids List of object IDs to fetch metadata for.
+ *           Accepts an array or a comma-separated list of numeric IDs.
+ *     @type string $object_type The type of object, eg 'groups' or 'activity'.
+ *     @type string $meta_table The name of the metadata table being queried.
+ *     @type string $object_column Optional. The name of the database column
+ *           where IDs (those provided by $object_ids) are found. Eg, 'group_id'
+ *           for the groups metadata tables. Default: $object_type . '_id'.
+ *     @type string $cache_key_prefix Optional. The prefix to use when creating
+ *           cache key names. Default: the value of $meta_table.
+ * }
+ * @return array|bool Metadata cache for the specified objects, or false on failure.
  */
 function bp_update_meta_cache( $args = array() ) {