Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
10/23/2013 06:47:12 PM (13 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-forums. See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r7338 r7468  
    11<?php
    22/**
    3  * BuddyPress Forums Functions
     3 * BuddyPress Forums Functions.
    44 *
    55 * @package BuddyPress
    … …  
    1313
    1414/**
    15  * Used to see if bbPress 2.x is installed and active
    16  *
    17  * @since BuddyPress (1.6)
    18  * @return boolean True if bbPress 2.x is active, false if not
     15 * Is see bbPress 2.x is installed and active?
     16 *
     17 * @since BuddyPress (1.6.0)
     18 *
     19 * @return boolean True if bbPress 2.x is active, false if not.
    1920 */
    2021function bp_forums_is_bbpress_active() {
    … …  
    3536
    3637/**
    37  * If the bb-config-location option exists, bbPress 1.x was previously installed
    38  *
    39  * @since BuddyPress (1.2)
    40  * @return boolean True if option exists, false if not
     38 * See if bbPress 1.x is installed correctly.
     39 *
     40 * "Installed correctly" means that the bb-config-location option is set, and
     41 * the referenced file exists.
     42 *
     43 * @since BuddyPress (1.2.0)
     44 *
     45 * @return boolean True if option exists, false if not.
    4146 */
    4247function bp_forums_is_installed_correctly() {
    … …  
    5055
    5156/**
     57 * Does the forums component have a directory page registered?
     58 *
    5259 * Checks $bp pages global and looks for directory page
    5360 *
    54  * @since BuddyPress (1.5)
    55  *
    56  * @global BuddyPress $bp The one true BuddyPress instance
    57  * @return bool True if set, False if empty
     61 * @since BuddyPress (1.5.0)
     62 *
     63 * @global BuddyPress $bp The one true BuddyPress instance.
     64 *
     65 * @return bool True if set, False if empty.
    5866 */
    5967function bp_forums_has_directory() {
    … …  
    6371/** Forum Functions ***********************************************************/
    6472
     73/**
     74 * Get a forum by ID.
     75 *
     76 * Wrapper for {@link bb_get_forum()}.
     77 *
     78 * @param int $forum_id ID of the forum being fetched.
     79 * @return object bbPress forum object.
     80 */
    6581function bp_forums_get_forum( $forum_id ) {
    6682        do_action( 'bbpress_init' );
    … …  
    6884}
    6985
     86/**
     87 * Create a forum.
     88 *
     89 * Wrapper for {@link bb_new_forum()}.
     90 *
     91 * @param array $args {
     92 *     Forum setup arguments.
     93 *     @type string $forum_name Name of the forum.
     94 *     @type string $forum_desc Description of the forum.
     95 *     @type int $forum_parent_id ID of the forum parent. Default: value of
     96 *           {@link bp_forums_parent_forums_id()}.
     97 *     @type bool $forum_order Order.
     98 *     @type int $forum_is_category Whether the forum is a category. Default: 0.
     99 * }
     100 * @return int ID of the newly created forum.
     101 */
    70102function bp_forums_new_forum( $args = '' ) {
    71103        do_action( 'bbpress_init' );
    … …  
    83115}
    84116
     117/**
     118 * Update a forum.
     119 *
     120 * Wrapper for {@link bb_update_forum(}.
     121 *
     122 * @param array $args {
     123 *     Forum setup arguments.
     124 *     @type int $forum_id ID of the forum to be updated.
     125 *     @type string $forum_name Name of the forum.
     126 *     @type string $forum_desc Description of the forum.
     127 *     @type int $forum_parent_id ID of the forum parent. Default: value of
     128 *           {@link bp_forums_parent_forums_id()}.
     129 *     @type bool $forum_order Order.
     130 *     @type int $forum_is_category Whether the forum is a category. Default: 0.
     131 * }
     132 * @return bool Ttrue on success, false on failure.
     133 */
    85134function bp_forums_update_forum( $args = '' ) {
    86135        do_action( 'bbpress_init' );
    … …  
    100149}
    101150
     151/**
     152 * Delete a group forum by the group id.
     153 *
     154 * @param int $group_id ID of the group whose forum is to be deleted.
     155 */
    102156function bp_forums_delete_group_forum( $group_id ) {
    103157        $forum_id = groups_get_groupmeta( $group_id, 'forum_id' );
    … …  
    112166/** Topic Functions ***********************************************************/
    113167
     168/**
     169 * Fetch a set of forum topics.
     170 *
     171 * @param array $args {
     172 *     @type string @type Order or filter type. Default: 'newest'.
     173 *     @type int $forum_id Optional. Pass a forum ID to limit results to topics
     174 *           associated with that forum.
     175 *     @type int $user_id Optional. Pass a user ID to limit results to topics
     176 *           belonging to that user.
     177 *     @type int $page Optional. Number of the results page to return.
     178 *           Default: 1.
     179 *     @type int $per_page Optional. Number of results to return per page.
     180 *           Default: 15.
     181 *     @type int $offset Optional. Numeric offset for results.
     182 *     @type int $number
     183 *     @type array $exclude Optional. Topic IDs to exclude.
     184 *     @type string $show_stickies Whether to show sticky topics.
     185 *     @type mixed $filter If $type = 'tag', filter is the tag name. Otherwise,
     186 *           $filter is terms to search on.
     187 * }
     188 * @return array Found topics.
     189 */
    114190function bp_forums_get_forum_topics( $args = '' ) {
    115191        do_action( 'bbpress_init' );
    … …  
    158234}
    159235
     236/**
     237 * Get additional details about a given forum topic.
     238 *
     239 * @param int $topic_id ID of the topic for which you're fetching details.
     240 * @return object Details about the topic.
     241 */
    160242function bp_forums_get_topic_details( $topic_id ) {
    161243        do_action( 'bbpress_init' );
    … …  
    166248}
    167249
     250/**
     251 * Get the numeric ID of a topic from the topic slug.
     252 *
     253 * Wrapper for {@link bb_get_id_from_slug()}.
     254 *
     255 * @param string $topic_slug Slug of the topic.
     256 * @return int|bool ID of the topic (if found), false on failure.
     257 */
    168258function bp_forums_get_topic_id_from_slug( $topic_slug ) {
    169259        do_action( 'bbpress_init' );
    … …  
    175265}
    176266
     267/**
     268 * Create a new forum topic.
     269 *
     270 * @param array $args {
     271 *     @type string $topic_title Title of the new topic.
     272 *     @type string $topic_slug Slug of the new topic.
     273 *     @type string $topic_text Text of the new topic.
     274 *     @type int $topic_poster ID of the user posting the topic. Default: ID of
     275 *           the logged-in user.
     276 *     @type string $topic_poster_name Display name of the user posting the
     277 *           topic. Default: 'fullname' of the logged-in user.
     278 *     @type id $topic_last_poster ID of the user who last posted to the topic.
     279 *           Default: ID of the logged-in user.
     280 *     @type string $topic_last_poster_name Display name of the user who last
     281 *           posted to the topic. Default: 'fullname' of the logged-in user.
     282 *     @type string $topic_start_time Date/time when the topic was created.
     283 *           Default: the current time, as reported by bp_core_current_time().
     284 *     @type string $topic_time Date/time when the topic was created.
     285 *           Default: the current time, as reported by bp_core_current_time().
     286 *     @type int $topic_open Whether the topic is open. Default: 1 (open).
     287 *     @type array|string|bool $topic_tags Array or comma-separated list of
     288 *           topic tags. False to leave empty. Default: false.
     289 *     @type int $forum_id ID of the forum to which the topic belongs.
     290 *           Default: 0.
     291 * }
     292 * @return object Details about the new topic, as returned by
     293 *         {@link bp_forums_get_topic_details()}.
     294 */
    177295function bp_forums_new_topic( $args = '' ) {
    178296        global $bp;
    … …  
    222340}
    223341
     342/**
     343 * Update a topic's details.
     344 *
     345 * @param array $args {
     346 *     Array of arguments.
     347 *     @type int $topic_id ID of the topic being updated.
     348 *     @type string $topic_title Updated title of the topic.
     349 *     @type string $topic_title Updated text of the topic.
     350 *     @type array|string|bool $topic_tags Array or comma-separated list of
     351 *           topic tags. False to leave empty. Default: false.
     352 * }
     353 * @return object Details about the new topic, as returned by
     354 *         {@link bp_forums_get_topic_details()}.
     355 */
    224356function bp_forums_update_topic( $args = '' ) {
    225357        do_action( 'bbpress_init' );
    … …  
    270402}
    271403
     404/**
     405 * Set a topic's open/closed status.
     406 *
     407 * @param array $args {
     408 *     @type int $topic_id ID of the topic whose status is being changed.
     409 *     @type string $mode New status of the topic. 'open' or 'close'.
     410 *           Default: 'close'.
     411 * }
     412 * @return bool True on success, false on failure.
     413 */
    272414function bp_forums_openclose_topic( $args = '' ) {
    273415        do_action( 'bbpress_init' );
    … …  
    287429}
    288430
     431/**
     432 * Delete a topic.
     433 *
     434 * @param array $args {
     435 *     @type int $topic_id ID of the topic being deleted.
     436 * }
     437 * @return bool True on success, false on failure.
     438 */
    289439function bp_forums_delete_topic( $args = '' ) {
    290440        do_action( 'bbpress_init' );
    … …  
    298448}
    299449
     450/**
     451 * Get a count of the total topics on the site.
     452 *
     453 * @return int $count Total topic count.
     454 */
    300455function bp_forums_total_topic_count() {
    301456        global $bbdb;
    … …  
    322477/**
    323478 * Check to see whether a user has already left this particular reply on a given post.
    324  * Prevents dupes.
    325  *
    326  * @since BuddyPress (1.6)
    327  *
    328  * @param string $text The text of the comment
    329  * @param int $topic_id The topic id
    330  * @param int $user_id The user id
     479 *
     480 * Used to prevent dupes.
     481 *
     482 * @since BuddyPress (1.6.0)
     483 *
     484 * @param string $text The text of the comment.
     485 * @param int $topic_id The topic id.
     486 * @param int $user_id The user id.
     487 * @return bool True if a duplicate reply exists, otherwise false.
    331488 */
    332489function bp_forums_reply_exists( $text = '', $topic_id = 0, $user_id = 0 ) {
    … …  
    361518         * Private one-time-use function used in conjunction with bp_forums_reply_exists()
    362519         *
    363          * @since BuddyPress (1.7)
    364520         * @access private
    365          * @global WPDB $wpdb
    366          * @param string $where
    367          * @return string
     521         * @since BuddyPress (1.7.0)
     522         *
     523         * @global WPDB $wpdb WordPress database access object.
     524         *
     525         * @param string $where SQL fragment.
     526         * @return string SQL fragment.
    368527         */
    369528        function _bp_forums_reply_exists_posts_where( $where = '' ) {
    … …  
    372531
    373532/**
    374  * Get a total "Topics Started" count for a given user
    375  *
    376  * @package BuddyPress
    377  *
    378  * @param int $user_id ID of the user being queried. Falls back on displayed user, then loggedin
    379  * @param string $type The current filter/sort type. 'active', 'popular', 'unreplied'
    380  * @return int $count The topic count
     533 * Get a total "Topics Started" count for a given user.
     534 *
     535 * @param int $user_id ID of the user being queried. Falls back on displayed
     536 *        user, then loggedin.
     537 * @param string $type The current filter/sort type. 'active', 'popular',
     538 *        'unreplied'.
     539 * @return int $count The topic count.
    381540 */
    382541function bp_forums_total_topic_count_for_user( $user_id = 0, $type = 'active' ) {
    … …  
    408567
    409568/**
    410  * Return the total number of topics replied to by a given user
    411  *
    412  * Uses an unfortunate technique to count unique topics, due to limitations in BB_Query.
    413  *
    414  * @package BuddyPress
    415  * @since BuddyPress (1.5)
    416  *
    417  * @param int $user_id Defaults to displayed user, then to logged-in user
    418  * @return int $count
     569 * Return the total number of topics replied to by a given user.
     570 *
     571 * Uses an unfortunate technique to count unique topics, due to limitations in
     572 * BB_Query.
     573 *
     574 * @since BuddyPress (1.5.0)
     575 *
     576 * @param int $user_id ID of the user whose replied topics are being counted.
     577 *        Defaults to displayed user, then to logged-in user.
     578 * @return int $count Topic count.
    419579 */
    420580function bp_forums_total_replied_count_for_user( $user_id = 0, $type = 'active' ) {
    … …  
    453613}
    454614
     615/**
     616 * Fetch BP-specific details for an array of topics.
     617 *
     618 * Done in one fell swoop to reduce query overhead. Currently determines the
     619 * following:
     620 * - details about the last poster
     621 * - information about topic users that may have been deleted/spammed
     622 *
     623 * @param array $topics Array of topics.
     624 * @return array $topics Topics with BP details added.
     625 */
    455626function bp_forums_get_topic_extras( $topics ) {
    456627        global $wpdb, $bbdb;
    … …  
    510681/** Post Functions ************************************************************/
    511682
     683/**
     684 * Get the posts belonging to a topic.
     685 *
     686 * @param array $args {
     687 *     @type int $topic_id ID of the topic for which posts are being fetched.
     688 *     @type int $page Optional. Page of results to return. Default: 1.
     689 *     @type int $page Optional. Number of results to return per page.
     690 *           Default: 15.
     691 *     @type string $order 'ASC' or 'DESC'. Default: 'ASC'.
     692 * }
     693 * @return array List of posts.
     694 */
    512695function bp_forums_get_topic_posts( $args = '' ) {
    513696        do_action( 'bbpress_init' );
    … …  
    526709}
    527710
     711/**
     712 * Get a single post object by ID.
     713 *
     714 * Wrapper for {@link bb_get_post()}.
     715 *
     716 * @param int $post_id ID of the post being fetched.
     717 * @return object Post object.
     718 */
    528719function bp_forums_get_post( $post_id ) {
    529720        do_action( 'bbpress_init' );
    … …  
    531722}
    532723
     724/**
     725 * Delete a post.
     726 *
     727 * Wrapper for {@link bb_delete_post()}.
     728 *
     729 * @param array $args {
     730 *     @type int $post_id ID of the post being deleted.
     731 * }
     732 * @return bool True on success, false on failure.
     733 */
    533734function bp_forums_delete_post( $args = '' ) {
    534735        do_action( 'bbpress_init' );
    … …  
    543744}
    544745
     746/**
     747 * Create a new post.
     748 *
     749 * @param array $args {
     750 *     @type int $post_id Optional. ID of an existing post, if you want to
     751 *           update rather than create. Default: false.
     752 *     @type int $topic_id ID of the topic to which the post belongs.
     753 *     @type string $post_text Contents of the post.
     754 *     @type string $post_time Optional. Time when the post was recorded.
     755 *           Default: current time, as reported by {@link bp_core_current_time()}.
     756 *     @type int $poster_id Optional. ID of the user creating the post.
     757 *           Default: ID of the logged-in user.
     758 *     @type string $poster_ip Optional. IP address of the user creating the
     759 *           post. Default: the IP address found in $_SERVER['REMOTE_ADDR'].
     760 *     @type int $post_status Post status. Default: 0.
     761 *     @type int $post_position Optional. Default: false (auto).
     762 * }
     763 * @return int|bool ID of the new post on success, false on failure.
     764 */
    545765function bp_forums_insert_post( $args = '' ) {
    546766        do_action( 'bbpress_init' );
    … …  
    589809}
    590810
     811/**
     812 * Get BP-specific details about a set of posts.
     813 *
     814 * Currently fetches the following:
     815 * - WP userdata for each poster
     816 * - BP fullname for each poster
     817 *
     818 * @param array $posts List of posts.
     819 * @return array Posts with BP-data added.
     820 */
    591821function bp_forums_get_post_extras( $posts ) {
    592822        global $bp, $wpdb;
    … …  
    627857}
    628858
     859/**
     860 * Get topic and post counts for a given forum.
     861 *
     862 * @param int $forum_id ID of the forum.
     863 * @return object Object with properties $topics (topic count) and $posts
     864 *         (post count).
     865 */
    629866function bp_forums_get_forum_topicpost_count( $forum_id ) {
    630867        global $wpdb, $bbdb;
    … …  
    636873}
    637874
     875/**
     876 * Map WordPress caps onto bbPress users, to ensure that they can post.
     877 *
     878 * @param array $allcaps Array of capabilities.
     879 * @return array Caps array with bbPress caps added.
     880 */
    638881function bp_forums_filter_caps( $allcaps ) {
    639882        global $wp_roles, $bb_table_prefix;
    … …  
    656899
    657900/**
    658  * Returns the parent forum id for the bbPress abstraction layer
    659  *
    660  * @package BuddyPress
    661  * @since BuddyPress (1.5)
    662  *
    663  * @return int
     901 * Return the parent forum ID for the bbPress abstraction layer.
     902 *
     903 * @since BuddyPress (1.5.0)
     904 *
     905 * @return int Forum ID.
    664906 */
    665907function bp_forums_parent_forum_id() {
    … …  
    670912 * Should sticky topics be broken out of regular topic order on forum directories?
    671913 *
    672  * Defaults to false. Define BP_FORUMS_ENABLE_GLOBAL_DIRECTORY_STICKIES, or filter
    673  * bp_forums_enable_global_directory_stickies, to change this behavior.
    674  *
    675  * @package BuddyPress
    676  * @since BuddyPress (1.5)
    677  *
    678  * @return bool True if stickies should be displayed at the top of the global directory, false
    679  *    otherwise.
     914 * Defaults to false. Define BP_FORUMS_ENABLE_GLOBAL_DIRECTORY_STICKIES, or
     915 * filter 'bp_forums_enable_global_directory_stickies', to change this behavior.
     916 *
     917 * @since BuddyPress (1.5.0)
     918 *
     919 * @return bool True if stickies should be displayed at the top of the global
     920 *         directory, otherwise false.
    680921 */
    681922function bp_forums_enable_global_directory_stickies() {
    … …  
    684925
    685926
    686 /********************************************************************************
    687  * Caching
    688  *
     927/** Caching ******************************************************************/
     928
     929/**
    689930 * Caching functions handle the clearing of cached objects and pages on specific
    690931 * actions throughout BuddyPress.
    … …  
    700941
    701942/**
     943 * Attempt to retrieve the oEmbed cache for a forum topic.
     944 *
    702945 * Grabs the topic post ID and attempts to retrieve the oEmbed cache (if it exists)
    703946 * during the forum topic loop.  If no cache and link is embeddable, cache it.
     947 *
     948 * @since BuddyPress (1.5.0)
    704949 *
    705950 * @see BP_Embed
    706951 * @see bp_embed_forum_cache()
    707952 * @see bp_embed_forum_save_cache()
    708  * @package BuddyPress_Forums
    709  * @since BuddyPress (1.5)
    710953 */
    711954function bp_forums_embed() {
    … …  
    717960
    718961/**
     962 * Used during {@link BP_Embed::parse_oembed()} via {@link bp_forums_embed()}.
     963 *
    719964 * Wrapper function for {@link bb_get_postmeta()}.
    720  * Used during {@link BP_Embed::parse_oembed()} via {@link bp_forums_embed()}.
    721965 *
    722966 * @package BuddyPress_Forums
    … …  
    728972
    729973/**
     974 * Used during {@link BP_Embed::parse_oembed()} via {@link bp_forums_embed()}.
     975 *
    730976 * Wrapper function for {@link bb_update_postmeta()}.
    731  * Used during {@link BP_Embed::parse_oembed()} via {@link bp_forums_embed()}.
    732  *
    733  * @package BuddyPress_Forums
    734  * @since BuddyPress (1.5)
     977 *
     978 * @since BuddyPress (1.5.0)
    735979 */
    736980function bp_embed_forum_save_cache( $cache, $cachekey, $id ) {
Note: See TracChangeset for help on using the changeset viewer.