Skip to:
Content

BuddyPress.org

Changeset 7407


Ignore:
Timestamp:
10/10/2013 02:44:05 PM (11 years ago)
Author:
boonebgorges
Message:

Inline docs improvements in Blogs component:

  • bp-blogs-actions.php
  • bp-blogs-activity.php
  • bp-blogs-buddybar.php
  • bp-blogs-cache.php
  • bp-blogs-classes.php

See #5022

Location:
trunk/bp-blogs
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-blogs/bp-blogs-actions.php

    r6975 r7407  
    22
    33/**
    4  * BuddyPress Blogs Actions
     4 * BuddyPress Blogs Actions.
    55 *
    66 * @package BuddyPress
    … …  
    1212
    1313/**
    14  * Redirect to a random blog in the multisite network
     14 * Redirect to a random blog in the multisite network.
    1515 *
    1616 * @since BuddyPress (1.0)
    17  * @package BuddyPress
    18  * @subpackage BlogsActions
    1917 */
    2018function bp_blogs_redirect_to_random_blog() {

  • trunk/bp-blogs/bp-blogs-activity.php

    r7228 r7407  
    22
    33/**
    4  * BuddyPress Blogs Activity
     4 * BuddyPress Blogs Activity.
    55 *
    66 * @package BuddyPress
    … …  
    1212
    1313/**
    14  * Register activity actions for the blogs component
     14 * Register activity actions for the blogs component.
    1515 *
    1616 * @since BuddyPress (1.0)
    17  * @package BuddyPress
    18  * @subpackage BlogsActivity
    19  * @global type $bp
    20  * @return boolean
     17 *
     18 * @global object $bp The BuddyPress global settings object.
     19 *
     20 * @return bool|null Returns false if activity component is not active.
    2121 */
    2222function bp_blogs_register_activity_actions() {
    … …  
    4040
    4141/**
    42  * Record the activity to the actvity stream
     42 * Record blog-related activity to the activity stream.
    4343 *
    4444 * @since BuddyPress (1.0)
    45  * @package BuddyPress
    46  * @subpackage BlogsActivity
    47  * @global BuddyPress $bp
    48  * @param array $args
    49  * @return boolean
     45 *
     46 * @see bp_activity_add() for description of parameters.
     47 * @global object $bp The BuddyPress global settings object.
     48 *
     49 * @param array $args {
     50 *     See {@link bp_activity_add()} for complete description of arguments.
     51 *     The arguments listed here have different default values from bp_activity_add().
     52 *     @type string $component Default: 'blogs'.
     53 * }
     54 * @return int|bool On success, returns the activity ID. False on failure.
    5055 */
    5156function bp_blogs_record_activity( $args = '' ) {
    … …  
    95100
    96101/**
    97  * Delete a blogs activity stream item
     102 * Delete a blog-related activity stream item.
    98103 *
    99104 * @since BuddyPress (1.0)
    100  * @package BuddyPress
    101  * @subpackage BlogsActivity
    102  * @global BuddyPress $bp
    103  * @param array $args
     105 *
     106 * @see bp_activity_delete() for description of parameters.
     107 * @global object $bp The BuddyPress global settings object.
     108 *
     109 * @param array $args {
     110 *     See {@link bp_activity_delete()} for complete description of arguments.
     111 *     The arguments listed here have different default values from bp_activity_add().
     112 *     @type string $component Default: 'blogs'.
     113 * }
     114 * @return bool True on success, false on failure.
    104115 */
    105116function bp_blogs_delete_activity( $args = true ) {

  • trunk/bp-blogs/bp-blogs-buddybar.php

    r6342 r7407  
    22
    33/**
    4  * BuddyPress Blogs Activity
     4 * BuddyPress Blogs BuddyBar functions.
    55 *
    66 * @package BuddyPress
    … …  
    1212
    1313/**
    14  * Add a Sites menu to the BuddyBar
     14 * Add a Sites menu to the BuddyBar.
    1515 *
    1616 * @since BuddyPress (1.0)
    17  * @package BuddyPress
    18  * @subpackage BlogsBuddyBar
    19  * @global BuddyPress $bp
    20  * @return boolean
     17 *
     18 * @global object $bp The BuddyPress global settings object.
     19 * @return bool|null Returns false on failure. Otherwise echoes the menu item.
    2120 */
    2221

  • trunk/bp-blogs/bp-blogs-cache.php

    r7228 r7407  
    22
    33/**
    4  * BuddyPress Blogs Caching
     4 * BuddyPress Blogs Caching.
    55 *
    66 * Caching functions handle the clearing of cached objects and pages on specific
    … …  
    1515
    1616/**
    17  * Clear the blog object cache
     17 * Clear the blog object cache.
    1818 *
    1919 * @since BuddyPress (1.0)
    20  * @package BuddyPress
    21  * @subpackage BlogsCache
    22  * @param int $blog_id
    23  * @param int $user_id
     20 *
     21 * @param int $blog_id ID of the current blog.
     22 * @param int $user_id ID of the user whose blog cache should be cleared.
    2423 */
    2524function bp_blogs_clear_blog_object_cache( $blog_id, $user_id ) {
    … …  
    2928
    3029/**
    31  * Clear cache when a new blog is created
     30 * Clear cache when a new blog is created.
    3231 *
    3332 * @since BuddyPress (1.0)
    34  * @package BuddyPress
    35  * @subpackage BlogsCache
    36  * @param BP_Blogs_Blog $recorded_blog_obj
     33 *
     34 * @param BP_Blogs_Blog $recorded_blog_obj The recorded blog, passed by 'bp_blogs_new_blog'.
    3735 */
    3836function bp_blogs_format_clear_blog_cache( $recorded_blog_obj ) {

  • trunk/bp-blogs/bp-blogs-classes.php

    r7317 r7407  
    22
    33/**
    4  * BuddyPress Blogs Classes
     4 * BuddyPress Blogs Classes.
    55 *
    66 * @package BuddyPress
    … …  
    1212
    1313/**
    14  * The main BuddyPress blog class
     14 * The main BuddyPress blog class.
     15 *
     16 * A BP_Blogs_Object represents a link between a specific WordPress blog on a
     17 * network and a specific user on that blog.
    1518 *
    1619 * @since BuddyPress (1.0)
    17  * @package BuddyPress
    18  * @subpackage BlogsClasses
    1920 */
    2021class BP_Blogs_Blog {
    … …  
    2324    public $blog_id;
    2425
     26    /**
     27     * Constructor method.
     28     *
     29     * @param int $id Optional. The ID of the blog.
     30     */
    2531    public function __construct( $id = null ) {
    2632        if ( !empty( $id ) ) {
    … …  
    3036    }
    3137
     38    /**
     39     * Populate the object with data about the specific activity item.
     40     */
    3241    public function populate() {
    3342        global $wpdb, $bp;
    … …  
    3948    }
    4049
     50    /**
     51     * Save the BP blog data to the database.
     52     *
     53     * @return bool True on success, false on failure.
     54     */
    4155    public function save() {
    4256        global $wpdb, $bp;
    … …  
    7488    }
    7589
     90    /**
     91     * Check whether an association between this user and this blog exists.
     92     *
     93     * @return int The number of associations between the user and blog
     94     *         saved in the blog component tables.
     95     */
    7696    public function exists() {
    7797        global $bp, $wpdb;
    … …  
    80100    }
    81101
    82     /* Static Functions */
    83 
     102    /** Static Methods ***************************************************/
     103
     104    /**
     105     * Retrieve a set of blog-user associations.
     106     *
     107     * @param string $type The order in which results should be returned.
     108     *        'active', 'alphabetical', 'newest', or 'random'.
     109     * @param int|bool $limit Optional. The maximum records to return.
     110     *        Default: false.
     111     * @param int|bool $page Optional. The page of records to return.
     112     *        Default: false (unlimited results).
     113     * @param int $user_id Optional. ID of the user whose blogs are being
     114     *        retrieved. Default: 0.
     115     * @param string|bool $search_terms Optional. Search by text stored in
     116     *        blogmeta (such as the blog name). Default: false.
     117     * @return array Multidimensional results array, structured as follows:
     118     *           'blogs' - Array of located blog objects
     119     *           'total' - A count of the total blogs matching the filter params
     120     */
    84121    public static function get( $type, $limit = false, $page = false, $user_id = 0, $search_terms = false ) {
    85122        global $bp, $wpdb;
    … …  
    128165    }
    129166
     167    /**
     168     * Delete the record of a given blog for all users.
     169     *
     170     * @param int $blog_id The blog being removed from all users.
     171     * @return int|bool Number of rows deleted on success, false on failure.
     172     */
    130173    public static function delete_blog_for_all( $blog_id ) {
    131174        global $wpdb, $bp;
    … …  
    135178    }
    136179
     180    /**
     181     * Delete the record of a given blog for a specific user.
     182     *
     183     * @param int $blog_id The blog being removed.
     184     * @param int $user_id Optional. The ID of the user from whom the blog
     185     *        is being removed. If absent, defaults to the logged-in user ID.
     186     * @return int|bool Number of rows deleted on success, false on failure.
     187     */
    137188    public static function delete_blog_for_user( $blog_id, $user_id = null ) {
    138189        global $wpdb, $bp;
    … …  
    144195    }
    145196
     197    /**
     198     * Delete all of a user's blog associations in the BP tables.
     199     *
     200     * @param int $user_id Optional. The ID of the user whose blog
     201     *        associations are being deleted. If absent, defaults to
     202     *        logged-in user ID.
     203     * @return int|bool Number of rows deleted on success, false on failure.
     204     */
    146205    public static function delete_blogs_for_user( $user_id = null ) {
    147206        global $wpdb, $bp;
    … …  
    153212    }
    154213
     214    /**
     215     * Get all of a user's blogs, as tracked by BuddyPress.
     216     *
     217     * Note that this is different from the WordPress function {@link get_blogs_of_user()};
     218     * the current method returns only those blogs that have been recorded
     219     * by BuddyPress, while the WP function does a true query of a user's
     220     * blog capabilities.
     221     *
     222     * @param int $user_id Optional. ID of the user whose blogs are being
     223     *        queried. Defaults to logged-in user.
     224     * @param bool $show_hidden Optional. Whether to include blogs that are
     225     *        not marked public. Defaults to true when viewing one's own
     226     *        profile.
     227     * @return array Multidimensional results array, structured as follows:
     228     *           'blogs' - Array of located blog objects
     229     *           'total' - A count of the total blogs for the user.
     230     */
    155231    public static function get_blogs_for_user( $user_id = 0, $show_hidden = false ) {
    156232        global $bp, $wpdb;
    … …  
    179255    }
    180256
     257    /**
     258     * Get IDs of all of a user's blogs, as tracked by BuddyPress.
     259     *
     260     * This method always includes hidden blogs.
     261     *
     262     * @param int $user_id Optional. ID of the user whose blogs are being
     263     *        queried. Defaults to logged-in user.
     264     * @return int The number of blogs associated with the user.
     265     */
    181266    public static function get_blog_ids_for_user( $user_id = 0 ) {
    182267        global $bp, $wpdb;
    … …  
    188273    }
    189274
     275    /**
     276     * Check whether a blog has been recorded by BuddyPress.
     277     *
     278     * @param int $blog_id ID of the blog being queried.
     279     * @return int|null The ID of the first located entry in the BP table
     280     *         on success, otherwise null.
     281     */
    190282    public static function is_recorded( $blog_id ) {
    191283        global $bp, $wpdb;
    … …  
    194286    }
    195287
     288    /**
     289     * Return a count of associated blogs for a given user.
     290     *
     291     * Includes hidden blogs when the logged-in user is the same as the
     292     * $user_id parameter, or when the logged-in user has the bp_moderate
     293     * cap.
     294     *
     295     * @param int $user_id Optional. ID of the user whose blogs are being
     296     *        queried. Defaults to logged-in user.
     297     * @return int Blog count for the user.
     298     */
    196299    public static function total_blog_count_for_user( $user_id = null ) {
    197300        global $bp, $wpdb;
    … …  
    208311    }
    209312
     313    /**
     314     * Return a list of blogs matching a search term.
     315     *
     316     * Matches against blog names and descriptions, as stored in the BP
     317     * blogmeta table.
     318     *
     319     * @param string $filter The search term.
     320     * @param int $limit Optional. The maximum number of items to return.
     321     *        Default: null (no limit).
     322     * @param int $page Optional. The page of results to return. Default:
     323     *        null (no limit).
     324     * @return array Multidimensional results array, structured as follows:
     325     *           'blogs' - Array of located blog objects
     326     *           'total' - A count of the total blogs matching the query.
     327     */
    210328    public static function search_blogs( $filter, $limit = null, $page = null ) {
    211329        global $wpdb, $bp;
    … …  
    227345    }
    228346
     347    /**
     348     * Retrieve a list of all blogs.
     349     *
     350     * Query will include hidden blogs if the logged-in user has the
     351     * 'bp_moderate' cap.
     352     *
     353     * @param int $limit Optional. The maximum number of items to return.
     354     *        Default: null (no limit).
     355     * @param int $page Optional. The page of results to return. Default:
     356     *        null (no limit).
     357     * @return array Multidimensional results array, structured as follows:
     358     *           'blogs' - Array of located blog objects
     359     *           'total' - A count of the total blogs.
     360     */
    229361    public static function get_all( $limit = null, $page = null ) {
    230362        global $bp, $wpdb;
    … …  
    239371    }
    240372
     373    /**
     374     * Retrieve a list of blogs whose names start with a given letter.
     375     *
     376     * Query will include hidden blogs if the logged-in user has the
     377     * 'bp_moderate' cap.
     378     *
     379     * @param string $letter. The letter you're looking for.
     380     * @param int $limit Optional. The maximum number of items to return.
     381     *        Default: null (no limit).
     382     * @param int $page Optional. The page of results to return. Default:
     383     *        null (no limit).
     384     * @return array Multidimensional results array, structured as follows:
     385     *           'blogs' - Array of located blog objects.
     386     *           'total' - A count of the total blogs matching the query.
     387     */
    241388    public static function get_by_letter( $letter, $limit = null, $page = null ) {
    242389        global $bp, $wpdb;
    … …  
    257404    }
    258405
     406    /**
     407     * Fetch blog data not caught in the main query and append it to results array.
     408     *
     409     * Gets the following information, which is either unavailable at the
     410     * time of the original query, or is more efficient to look up in one
     411     * fell swoop:
     412     *   - The latest post for each blog, include Featured Image data
     413     *   - The blog description
     414     *
     415     * @param array $paged_blogs Array of results from the original query.
     416     * @param array $blog_ids Array of IDs returned from the original query.
     417     * @param string|bool $type Not currently used. Default: false.
     418     * @return array $paged_blogs The located blogs array, with the extras added.
     419     */
    259420    public static function get_blog_extras( &$paged_blogs, &$blog_ids, $type = false ) {
    260421        global $bp, $wpdb;
    … …  
    311472    }
    312473
     474    /**
     475     * Check whether a given blog is hidden.
     476     *
     477     * Checks the 'public' column in the wp_blogs table.
     478     *
     479     * @param int $blog_id The ID of the blog being checked.
     480     * @return bool True if hidden (public = 0), false otherwise.
     481     */
    313482    public static function is_hidden( $blog_id ) {
    314483        global $wpdb;
Note: See TracChangeset for help on using the changeset viewer.