Skip to:
Content

BuddyPress.org

Changeset 7409


Ignore:
Timestamp:
10/10/2013 06:34:00 PM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in Blogs component.

See #5022.

Location:
trunk/bp-blogs
Files:
2 edited

Legend:

Unmodified
Added
Removed

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

    r6477 r7409  
    99 */
    1010
    11 // Display filters
     11/** Display Filters **********************************************************/
    1212
    1313add_filter( 'bp_get_blog_latest_post_title', 'wptexturize'   );
    … …  
    2323
    2424/**
    25  * Ensures that the 'Create a new site' link at wp-admin/my-sites.php points to the BP blog signup
     25 * Ensure that the 'Create a new site' link at wp-admin/my-sites.php points to the BP blog signup
    2626 *
    2727 * @since BuddyPress (1.6)
    28  * @uses apply_filters() Filter bp_blogs_creation_location to alter the returned value
    2928 *
    30  * @param string $url The original URL (points to wp-signup.php by default)
    31  * @return string The new URL
     29 * @uses apply_filters() Filter 'bp_blogs_creation_location' to alter the
     30 *       returned value.
     31 *
     32 * @param string $url The original URL (points to wp-signup.php by default).
     33 * @return string The new URL.
    3234 */
    3335function bp_blogs_creation_location( $url ) {

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

    r7349 r7409  
    11<?php
    22/**
    3  * Blogs component functions
     3 * Blogs component functions.
    44 *
    55 * @package BuddyPress
    … …  
    1111
    1212/**
    13  * Checks $bp pages global and looks for directory page
     13 * Check whether the $bp global lists an activity directory page.
    1414 *
    1515 * @since BuddyPress (1.5)
    1616 *
    17  * @global BuddyPress $bp The one true BuddyPress instance
    18  * @return bool True if set, False if empty
     17 * @global BuddyPress $bp The one true BuddyPress instance.
     18 *
     19 * @return bool True if set, false if empty.
    1920 */
    2021function bp_blogs_has_directory() {
    … …  
    2425}
    2526
     27/**
     28 * Retrieve a set of blogs
     29 *
     30 * @see BP_Blogs_Blog::get() for a description of arguments and return value.
     31 *
     32 * @param array $args {
     33 *     Arguments are listed here with their default values. For more
     34 *     information about the arguments, see {@link BP_Blogs_Blog::get()}.
     35 *     @type string $type Default: 'active'.
     36 *     @type int|bool $user_id Default: false.
     37 *     @type string|bool $search_terms Default: false.
     38 *     @type int $per_page Default: 20.
     39 *     @type int $page Default: 1.
     40 * }
     41 * @return array See {@link BP_Blogs_Blog::get()}.
     42 */
    2643function bp_blogs_get_blogs( $args = '' ) {
    2744
    … …  
    4158
    4259/**
    43  * Populates the BP blogs table with existing blogs.
    44  *
    45  * @package BuddyPress Blogs
     60 * Populate the BP blogs table with existing blogs.
    4661 *
    4762 * @global object $bp BuddyPress global settings
    … …  
    8095
    8196/**
    82  * Makes BuddyPress aware of sites that shouldn't be recorded to activity streams.
     97 * Check whether a given blog should be recorded in activity streams.
    8398 *
    8499 * If $user_id is provided, you can restrict site from being recordable
    … …  
    86101 *
    87102 * @since BuddyPress (1.7)
    88  * @param int $blog_id
    89  * @param int|null $user_id
     103 *
    90104 * @uses apply_filters()
    91  * @return bool True if blog is recordable, false elsewhere
     105 *
     106 * @param int $blog_id ID of the blog being checked.
     107 * @param int $user_id Optional. ID of the user for whom access is being checked.
     108 * @return bool True if blog is recordable, otherwise false.
    92109 */
    93110function bp_blogs_is_blog_recordable( $blog_id, $user_id = 0 ) {
    … …  
    109126
    110127/**
    111  * Makes BuddyPress aware of sites that activities shouldn't be trackable.
     128 * Check whether a given blog should be tracked by the Blogs component.
     129 *
    112130 * If $user_id is provided, the developer can restrict site from
    113131 * being trackable only to particular users.
    114132 *
    115133 * @since BuddyPress (1.7)
    116  * @param int $blog_id
    117  * @param int|null $user_id
     134 *
    118135 * @uses bp_blogs_is_blog_recordable
    119136 * @uses apply_filters()
    120  * @return bool True if blog is trackable, false elsewhere
     137 *
     138 * @param int $blog_id ID of the blog being checked.
     139 * @param int $user_id Optional. ID of the user for whom access is being checked.
     140 * @return bool True if blog is trackable, otherwise false.
    121141 */
    122142function bp_blogs_is_blog_trackable( $blog_id, $user_id = 0 ) {
    … …  
    138158
    139159/**
    140  * Makes BuddyPress aware of a new site so that it can track its activity.
     160 * Make BuddyPress aware of a new site so that it can track its activity.
    141161 *
    142162 * @since BuddyPress (1.0)
    143  * @param int $blog_id
    144  * @param int $user_id
    145  * @param bool $no_activity Optional; defaults to false
     163 *
    146164 * @uses BP_Blogs_Blog
     165 *
     166 * @param int $blog_id ID of the blog being recorded.
     167 * @param int $user_id ID of the user for whom the blog is being recorded.
     168 * @param bool $no_activity Optional. Whether to skip recording an activity
     169 *        item about this blog creation. Default: false.
     170 * @return bool|null Returns false on failure.
    147171 */
    148172function bp_blogs_record_blog( $blog_id, $user_id, $no_activity = false ) {
    … …  
    192216
    193217/**
    194  * Updates blogname in BuddyPress blogmeta table
    195  *
    196  * @global object $wpdb DB Layer
    197  * @param string $oldvalue Value before save (not used)
    198  * @param string $newvalue Value to change meta to
     218 * Update blog name in BuddyPress blogmeta table.
     219 *
     220 * @global object $wpdb DB Layer.
     221 *
     222 * @param string $oldvalue Value before save. Passed by do_action() but unused here.
     223 * @param string $newvalue Value to change meta to.
    199224 */
    200225function bp_blogs_update_option_blogname( $oldvalue, $newvalue ) {
    … …  
    206231
    207232/**
    208  * Updates blogdescription in BuddyPress blogmeta table
    209  *
    210  * @global object $wpdb DB Layer
    211  * @param string $oldvalue Value before save (not used)
    212  * @param string $newvalue Value to change meta to
     233 * Update blog description in BuddyPress blogmeta table
     234 *
     235 * @global object $wpdb DB Layer.
     236 *
     237 * @param string $oldvalue Value before save. Passed by do_action() but unused here.
     238 * @param string $newvalue Value to change meta to.
    213239 */
    214240function bp_blogs_update_option_blogdescription( $oldvalue, $newvalue ) {
    … …  
    219245add_action( 'update_option_blogdescription', 'bp_blogs_update_option_blogdescription', 10, 2 );
    220246
     247/**
     248 * Record a new blog post in the BuddyPress activity stream.
     249 *
     250 * @param int $post_id ID of the post being recorded.
     251 * @param object $post The WP post object passed to the 'save_post' action.
     252 * @param int $user_id Optional. The user to whom the activity item will be
     253 *        associated. Defaults to the post_author.
     254 * @return bool|null Returns false on failure.
     255 */
    221256function bp_blogs_record_post( $post_id, $post, $user_id = 0 ) {
    222257    global $bp, $wpdb;
    … …  
    301336
    302337/**
    303  * Record blog comment activity. Checks if blog is public and post is not
    304  * password protected.
    305  *
    306  * @param int $comment_id
    307  * @param mixed $is_approved
    308  * @return mixed
     338 * Record a new blog comment in the BuddyPress activity stream.
     339 *
     340 * Only posts the item if blog is public and post is not password-protected.
     341 *
     342 * @param int $comment_id ID of the comment being recorded.
     343 * @param bool|string $is_approved Optional. The $is_approved value passed to
     344 *        the 'comment_post' action. Default: true.
     345 * @return bool|object Returns false on failure, the comment object on success.
    309346 */
    310347function bp_blogs_record_comment( $comment_id, $is_approved = true ) {
    … …  
    392429add_action( 'edit_comment', 'bp_blogs_record_comment', 10    );
    393430
     431/**
     432 * Record a user's association with a blog.
     433 *
     434 * This function is hooked to several WordPress actions where blog roles are
     435 * set/changed ('add_user_to_blog', 'profile_update', 'user_register'). It
     436 * parses the changes, and records them as necessary in the BP blog tracker.
     437 *
     438 * BuddyPress does not track blogs for Subscribers.
     439 *
     440 * @param int $user_id The ID of the user.
     441 * @param string|bool $role The WP role being assigned to the user
     442 *        ('subscriber', 'contributor', 'author', 'editor', 'administrator', or
     443 *        a custom role). Defaults to false.
     444 * @param int $blog_id Default: the current blog ID.
     445 * @return bool|null False on failure.
     446 */
    394447function bp_blogs_add_user_to_blog( $user_id, $role = false, $blog_id = 0 ) {
    395448    global $wpdb;
    … …  
    417470add_action( 'user_register',    'bp_blogs_add_user_to_blog'        );
    418471
     472/**
     473 * Remove a blog-user pair from BP's blog tracker.
     474 *
     475 * @param int $user_id ID of the user whose blog is being removed.
     476 * @param int $blog_id Optional. ID of the blog being removed. Default: current blog ID.
     477 */
    419478function bp_blogs_remove_user_from_blog( $user_id, $blog_id = 0 ) {
    420479    global $wpdb;
    … …  
    428487
    429488/**
    430  * Rehooks WP's maybe_add_existing_user_to_blog with a later priority
    431  *
    432  * WordPress catches add-user-to-blog requests at init:10. In some cases, this can precede BP's
    433  * Blogs component. This function bumps the priority of the core function, so that we can be sure
    434  * that the Blogs component is loaded first. See http://buddypress.trac.wordpress.org/ticket/3916
     489 * Rehook WP's maybe_add_existing_user_to_blog with a later priority
     490 *
     491 * WordPress catches add-user-to-blog requests at init:10. In some cases, this
     492 * can precede BP's Blogs component. This function bumps the priority of the
     493 * core function, so that we can be sure that the Blogs component is loaded
     494 * first. See http://buddypress.trac.wordpress.org/ticket/3916.
    435495 *
    436496 * @since BuddyPress (1.6)
     497 * @access private
    437498 */
    438499function bp_blogs_maybe_add_user_to_blog() {
    … …  
    445506add_action( 'init', 'bp_blogs_maybe_add_user_to_blog', 1 );
    446507
     508/**
     509 * Remove the "blog created" item from the BP blogs tracker and activity stream.
     510 *
     511 * @param int $blog_id ID of the blog being removed.
     512 */
    447513function bp_blogs_remove_blog( $blog_id ) {
    448514    global $bp;
    … …  
    460526add_action( 'delete_blog', 'bp_blogs_remove_blog' );
    461527
     528/**
     529 * Remove a blog from the tracker for a specific user.
     530 *
     531 * @param int $user_id ID of the user for whom the blog is being removed.
     532 * @param int $blog_id ID of the blog being removed.
     533 */
    462534function bp_blogs_remove_blog_for_user( $user_id, $blog_id ) {
    463535    global $bp;
    … …  
    481553add_action( 'remove_user_from_blog', 'bp_blogs_remove_blog_for_user', 10, 2 );
    482554
     555/**
     556 * Remove a blog post activity item from the activity stream.
     557 *
     558 * @param int $post_id ID of the post to be removed.
     559 * @param int $blog_id Optional. Defaults to current blog ID.
     560 * @param int $user_id Optional. Defaults to the logged-in user ID. This param
     561 *        is currently unused in the function (but is passed to hooks).
     562 */
    483563function bp_blogs_remove_post( $post_id, $blog_id = 0, $user_id = 0 ) {
    484564    global $wpdb, $bp;
    … …  
    504584add_action( 'delete_post', 'bp_blogs_remove_post' );
    505585
     586/**
     587 * Remove a blog comment activity item from the activity stream.
     588 *
     589 * @param int $comment_id ID of the comment to be removed.
     590 */
    506591function bp_blogs_remove_comment( $comment_id ) {
    507592    global $wpdb;
    … …  
    517602 * When a blog comment status transition occurs, update the relevant activity's status.
    518603 *
    519  * @global object $bp BuddyPress global settings
     604 * @since BuddyPress (1.6)
     605 *
     606 * @global object $bp BuddyPress global settings.
     607 *
    520608 * @param string $new_status New comment status.
    521609 * @param string $old_status Previous comment status.
    522610 * @param object $comment Comment data.
    523  * @since BuddyPress (1.6)
    524611 */
    525612function bp_blogs_transition_activity_status( $new_status, $old_status, $comment ) {
    … …  
    586673add_action( 'transition_comment_status', 'bp_blogs_transition_activity_status', 10, 3 );
    587674
     675/**
     676 * Get the total number of blogs being tracked by BuddyPress.
     677 *
     678 * @return int $count Total blog count.
     679 */
    588680function bp_blogs_total_blogs() {
    589681    if ( !$count = wp_cache_get( 'bp_total_blogs', 'bp' ) ) {
    … …  
    595687}
    596688
     689/**
     690 * Get the total number of blogs being tracked by BP for a specific user.
     691 *
     692 * @param int $user_id ID of the user being queried. Default: on a user page,
     693 *        the displayed user. Otherwise, the logged-in user.
     694 * @return int $count Total blog count for the user.
     695 */
    597696function bp_blogs_total_blogs_for_user( $user_id = 0 ) {
    598697
    … …  
    608707}
    609708
     709/**
     710 * Remove the all data related to a given blog from the BP blogs tracker and activity stream.
     711 *
     712 * @param int $blog_id The ID of the blog to expunge.
     713 */
    610714function bp_blogs_remove_data_for_blog( $blog_id ) {
    611715    global $bp;
    … …  
    623727add_action( 'delete_blog', 'bp_blogs_remove_data_for_blog', 1 );
    624728
     729/**
     730 * Get all of a user's blogs, as tracked by BuddyPress.
     731 *
     732 * @see BP_Blogs_Blog::get_blogs_for_user() for a description of parameters
     733 *      and return values.
     734 *
     735 * @param int $user_id See {@BP_Blogs_Blog::get_blogs_for_user()}.
     736 * @param bool $show_hidden See {@BP_Blogs_Blog::get_blogs_for_user()}.
     737 * @return array See {@BP_Blogs_Blog::get_blogs_for_user()}.
     738 */
    625739function bp_blogs_get_blogs_for_user( $user_id, $show_hidden = false ) {
    626740    return BP_Blogs_Blog::get_blogs_for_user( $user_id, $show_hidden );
    627741}
    628742
     743/**
     744 * Retrieve a list of all blogs.
     745 *
     746 * @see BP_Blogs_Blog::get_all() for a description of parameters and return values.
     747 *
     748 * @param int $limit See {@BP_Blogs_Blog::get_all()}.
     749 * @param int $page See {@BP_Blogs_Blog::get_all()}.
     750 * @return array See {@BP_Blogs_Blog::get_all()}.
     751 */
    629752function bp_blogs_get_all_blogs( $limit = null, $page = null ) {
    630753    return BP_Blogs_Blog::get_all( $limit, $page );
    631754}
    632755
     756/**
     757 * Retrieve a random list of blogs.
     758 *
     759 * @see BP_Blogs_Blog::get() for a description of parameters and return values.
     760 *
     761 * @param int $limit See {@BP_Blogs_Blog::get()}.
     762 * @param int $page See {@BP_Blogs_Blog::get()}.
     763 * @return array See {@BP_Blogs_Blog::get()}.
     764 */
    633765function bp_blogs_get_random_blogs( $limit = null, $page = null ) {
    634766    return BP_Blogs_Blog::get( 'random', $limit, $page );
    635767}
    636768
     769/**
     770 * Check whether a given blog is hidden.
     771 *
     772 * @see BP_Blogs_Blog::is_hidden() for a description of parameters and return values.
     773 *
     774 * @param int $blog_id See {@BP_Blogs_Blog::is_hidden()}.
     775 * @return bool See {@BP_Blogs_Blog::is_hidden()}.
     776 */
    637777function bp_blogs_is_blog_hidden( $blog_id ) {
    638778    return BP_Blogs_Blog::is_hidden( $blog_id );
    … …  
    648788 */
    649789
     790/**
     791 * Delete a metadta from the DB for a blog.
     792 *
     793 * @global object $wpdb WordPress database access object.
     794 * @global object $bp BuddyPress global settings.
     795 *
     796 * @param int $blog_id ID of the blog whose metadata is being deleted.
     797 * @param string $meta_key Optional. The key of the metadata being deleted. If
     798 *        omitted, all BP metadata associated with the blog will be deleted.
     799 * @param string $meta_value Optional. If present, the metadata will only be
     800 *        deleted if the meta_value matches this parameter.
     801 * @return bool True on success, false on failure.
     802 */
    650803function bp_blogs_delete_blogmeta( $blog_id, $meta_key = false, $meta_value = false ) {
    651804    global $wpdb, $bp;
    … …  
    673826}
    674827
     828/**
     829 * Get metadata for a given blog.
     830 *
     831 * @since BuddyPress (1.2)
     832 *
     833 * @global object $wpdb WordPress database access object.
     834 * @global object $bp BuddyPress global settings.
     835 *
     836 * @param int $blog_id ID of the blog whose metadata is being requested.
     837 * @param string $meta_key Optional. If present, only the metadata matching
     838 *        that meta key will be returned. Otherwise, all metadata for the
     839 *        blog will be fetched.
     840 * @return mixed The meta value(s) being requested.
     841 */
    675842function bp_blogs_get_blogmeta( $blog_id, $meta_key = '') {
    676843    global $wpdb, $bp;
    … …  
    707874}
    708875
     876/**
     877 * Update a piece of blog meta.
     878 *
     879 * @global object $wpdb WordPress database access object.
     880 * @global object $bp BuddyPress global settings.
     881 *
     882 * @param int $blog_id ID of the blog whose metadata is being updated.
     883 * @param string $meta_key Key of the metadata being updated.
     884 * @param mixed $meta_value Value to be set.
     885 * @return bool True on success, false on failure.
     886 */
    709887function bp_blogs_update_blogmeta( $blog_id, $meta_key, $meta_value ) {
    710888    global $wpdb, $bp;
    … …  
    737915}
    738916
     917/**
     918 * Remove all blog associations for a given user.
     919 *
     920 * @param int $user_id ID whose blog data should be removed.
     921 * @return bool|null Returns false on failure.
     922 */
    739923function bp_blogs_remove_data( $user_id ) {
    740924    if ( !is_multisite() )
Note: See TracChangeset for help on using the changeset viewer.