Skip to:
Content

BuddyPress.org

Changeset 7468


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

Improve inline docs in bp-forums. See #5022

Location:
trunk/bp-forums
Files:
4 edited

Legend:

Unmodified
Added
Removed

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

    r7298 r7468  
    11<?php
    22/**
    3  * BuddyPress Forums Actions
     3 * BuddyPress Forums Actions.
    44 *
    55 * @package BuddyPress

  • trunk/bp-forums/bp-forums-bbpress-sa.php

    r7298 r7468  
    11<?php
    22/**
    3  * BuddyPress bbPress 1.x integration
     3 * BuddyPress bbPress 1.x integration.
    44 *
    55 * @package BuddyPress
    … …  
    1010if ( !defined( 'ABSPATH' ) ) exit;
    1111
     12/**
     13 * Bootstrap bbPress 1.x, and manipulate globals to integrate with BuddyPress.
     14 *
     15 * @return bool|null Returns false on failure.
     16 */
    1217function bp_forums_load_bbpress() {
    1318    global $bp, $wpdb, $wp_roles, $current_user, $wp_users_object;
    … …  
    122127add_action( 'bbpress_init', 'bp_forums_load_bbpress' );
    123128
    124 /* WP to bbP wrapper functions */
     129/** WP to bbPress wrapper functions ******************************************/
     130
     131/**
     132 * Get the current bbPress user.
     133 *
     134 * @return object $current_user Current user object from WordPress.
     135 */
    125136function bb_get_current_user() { global $current_user; return $current_user; }
     137
     138/**
     139 * Get userdata for a bbPress user.
     140 *
     141 * @param int $user_id User ID.
     142 * @return object User data from WordPress.
     143 */
    126144function bb_get_user( $user_id ) { return get_userdata( $user_id ); }
     145
     146/**
     147 * Cache users.
     148 *
     149 * Noop.
     150 *
     151 * @param array $users
     152 */
    127153function bb_cache_users( $users ) {}
    128154
    … …  
    141167
    142168/**
    143  * bbPress needs the DB class to be BPDB, but we want to use WPDB, so we can
    144  * extend it and use this.
     169 * bbPress needs the DB class to be BPDB, but we want to use WPDB, so we can extend it and use this.
    145170 *
    146171 * The class is pluggable, so that plugins that swap out WPDB with a custom
    … …  
    152177        var $db_servers = array();
    153178
     179        /**
     180         * Constructor
     181         *
     182         * @see WPDB::__construct() for description of parameters.
     183         */
    154184        function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) {
    155185            parent::__construct( $dbuser, $dbpassword, $dbname, $dbhost );
    … …  
    165195         * Determine if a database supports a particular feature.
    166196         *
    167          * Overriden here to work around differences between bbPress', and WordPress', implementation differences.
    168          * In particular, when BuddyPress tries to run bbPress' SQL installation script, the collation check always
    169          * failed. The capability is long supported by WordPress' minimum required MySQL version, so this is safe.
     197         * Overriden here to work around differences between bbPress's
     198         * and WordPress's implementations. In particular, when
     199         * BuddyPress tries to run bbPress' SQL installation script,
     200         * the collation check always failed. The capability is long
     201         * supported by WordPress' minimum required MySQL version, so
     202         * this is safe.
     203         *
     204         * @see WPDB::has_cap() for a description of parameters and
     205         *      return values.
     206         *
     207         * @param string $db_cap See {@link WPDB::has_cap()}.
     208         * @param string $_table_name See {@link WPDB::has_cap()}.
     209         * @return bool See {@link WPDB::has_cap()}.
    170210         */
    171211        function has_cap( $db_cap, $_table_name='' ) {
    … …  
    177217
    178218        /**
    179          * Initialises the class variables based on provided arguments.
    180          * Based on, and taken from, the BackPress class in turn taken from the 1.0 branch of bbPress.
     219         * Initialize the class variables based on provided arguments.
     220         *
     221         * Based on, and taken from, the BackPress class in turn taken
     222         * from the 1.0 branch of bbPress.
     223         *
     224         * @see BBDB::__construct() for a description of params.
    181225         */
    182226        function init( $args ) {
    … …  
    205249        }
    206250
     251        /**
     252         * Stub for escape_deep() compatibility.
     253         *
     254         * @see WPDB::escape_deep() for description of parameters and
     255         *      return values.
     256         *
     257         * @param mixed $data See {@link WPDB::escape_deep()}.
     258         * @return mixed $data See {@link WPDB::escape_deep()}.
     259         */
    207260        function escape_deep( $data ) {
    208261            return $this->escape( $data );
    … …  
    211264endif; // class_exists( 'BPDB' )
    212265
    213 /* BBPress needs this function to convert vars */
     266/**
     267 * Convert object to given output format.
     268 *
     269 * bbPress needs this to convert vars.
     270 *
     271 * @param object $object Object to convert.
     272 * @param string $output Type of object to return. OBJECT, ARRAY_A, or ARRAY_N.
     273 */
    214274function backpress_convert_object( &$object, $output ) {
    215275    if ( is_array( $object ) ) {
    … …  
    226286
    227287/**
     288 * Parse and execute queries for updating a set of database tables.
     289 *
    228290 * Copied from wp-admin/includes/upgrade.php, this will take care of creating
    229291 * the bbPress stand-alone tables without loading a conflicting WP Admin.
    230292 *
    231  * @param array $queries
    232  * @param bool $execute Optional; defaults to true.
    233  * @return array
     293 * @see dbDelta() for a description of parameters and return value.
     294 *
     295 * @param array $queries See {@link dbDelta()}.
     296 * @param bool $execute See {@link dbDelta()}.
     297 * @return array See {@link dbDelta()}.
    234298 */
    235299function bp_bb_dbDelta($queries, $execute = true) {

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

    r7298 r7468  
    11<?php
    22/**
    3  * BuddyPress Forums Filters
     3 * BuddyPress Forums Filters.
    44 *
    55 * @package BuddyPress
    … …  
    5555add_filter( 'bp_get_the_topic_post_content', 'bp_forums_make_nofollow_filter' );
    5656
     57/**
     58 * Custom KSES filter for the Forums component.
     59 *
     60 * @param string $content Content to sanitize.
     61 * @return string Sanitized string.
     62 */
    5763function bp_forums_filter_kses( $content ) {
    5864    global $allowedtags;
    … …  
    8288}
    8389
     90/**
     91 * Get a link for a forum topic tags directory.
     92 *
     93 * @param string $link Link passed from filter.
     94 * @param string $tag Name of the tag.
     95 * @param string $page Page number, passed from the filter.
     96 * @param string $context Passed from the filter but unused here.
     97 * @return string Link of the form http://example.com/forums/tag/tagname/.
     98 */
    8499function bp_forums_filter_tag_link( $link, $tag, $page, $context ) {
    85100    global $bp;
    … …  
    89104add_filter( 'bb_get_tag_link', 'bp_forums_filter_tag_link', 10, 4);
    90105
     106/**
     107 * Add rel="nofollow" to bbPress content.
     108 *
     109 * @param string $text Post content.
     110 * @return string Modified post content.
     111 */
    91112function bp_forums_make_nofollow_filter( $text ) {
    92113    return preg_replace_callback( '|<a (.+?)>|i', 'bp_forums_make_nofollow_filter_callback', $text );
    93114}
     115    /**
     116     * Callback for preg_replace_callback() in bp_forums_make_nofollow_filter().
     117     *
     118     * @param array $matches Regex matches from {@link bp_forums_make_nofollow_filter()}.
     119     * @return string Text with nofollow links.
     120     */
    94121    function bp_forums_make_nofollow_filter_callback( $matches ) {
    95122        $text = $matches[1];
    … …  
    99126
    100127/**
    101  * bp_forums_add_forum_topic_to_page_title( $title )
    102  *
    103  * Append forum topic to page title
    104  *
    105  * @global object $bp
    106  * @param string $title New page title; see bp_modify_page_title()
    107  * @param string $title Original page title
     128 * Append forum topic to page title.
     129 *
     130 * @global object $bp Global BuddyPress settings object.
     131 *
     132 * @see bp_modify_page_title()
     133 *
     134 * @param string $title New page title; see {@link bp_modify_page_title()}.
     135 * @param string $original_title Original page title.
    108136 * @param string $sep How to separate the various items within the page title.
    109  * @param string $seplocation Direction to display title
    110  * @return string
    111  * @see bp_modify_page_title()
     137 * @param string $seplocation Direction to display title.
     138 * @return string Page title with forum topic title appended.
    112139 */
    113140function bp_forums_add_forum_topic_to_page_title( $title, $original_title, $sep, $seplocation  ) {
    … …  
    123150
    124151/**
    125  * bp_forums_strip_mentions_on_post_edit( $title )
    126  *
    127  * Removes the anchor tag autogenerated for at-mentions when forum topics and posts are edited.
     152 * Remove the anchor tag autogenerated for at-mentions when forum topics and posts are edited.
     153 *
    128154 * Prevents embedded anchor tags.
    129155 *
    130  * @global object $bp
    131  * @param string $content
    132  * @return string $content
     156 * @global object $bp Global BuddyPress settings object.
     157 *
     158 * @param string $content Edited post content.
     159 * @return string $content Sanitized post content.
    133160 */
    134161function bp_forums_strip_mentions_on_post_edit( $content ) {
    … …  
    146173add_filter( 'bp_get_the_topic_text', 'bp_forums_strip_mentions_on_post_edit' );
    147174
    148 /**
    149  * "REPLIED TO" SQL FILTERS
    150  */
    151 
    152 /**
    153  * Filters the get_topics_distinct portion of the Forums sql when on a user's Replied To page.
    154  *
    155  * This filter is added in bp_has_forum_topics()
    156  *
    157  * @package BuddyPress
    158  * @since BuddyPress (1.5)
    159  *
    160  * @param string $sql
    161  * @return string $sql
     175/** "Replied to" SQL filters *************************************************/
     176
     177/**
     178 * Filter the get_topics_distinct portion of the Forums SQL when on a user's Replied To page.
     179 *
     180 * This filter is added in bp_has_forum_topics().
     181 *
     182 * @since BuddyPress (1.5.0)
     183 *
     184 * @param string $sql SQL fragment.
     185 * @return string $sql SQL fragment of the form "DISTINCT t.topic_id, ".
    162186 */
    163187function bp_forums_add_replied_distinct_sql( $sql ) {
    … …  
    168192
    169193/**
    170  * Filters the get_topics_join portion of the Forums sql when on a user's Replied To page.
    171  *
    172  * This filter is added in bp_has_forum_topics()
    173  *
    174  * @package BuddyPress
    175  * @since BuddyPress (1.5)
    176  *
    177  * @global object $bbdb The bbPress database global
    178  * @global object $wpdb The WordPress database global
    179  * @param string $sql
    180  * @return string $sql
     194 * Filter the get_topics_join portion of the Forums sql when on a user's Replied To page.
     195 *
     196 * This filter is added in bp_has_forum_topics().
     197 *
     198 * @since BuddyPress (1.5.0)
     199 *
     200 * @global object $bbdb The bbPress database global.
     201 *
     202 * @param string $sql SQL statement.
     203 * @return string $sql SQL statement.
    181204 */
    182205function bp_forums_add_replied_join_sql( $sql ) {
    … …  
    189212
    190213/**
    191  * Filters the get_topics_where portion of the Forums sql when on a user's Replied To page.
    192  *
    193  * This filter is added in bp_has_forum_topics()
    194  *
    195  * @package BuddyPress
    196  * @since BuddyPress (1.5)
    197  *
    198  * @global object $wpdb The WordPress database global
    199  * @param string $sql
    200  * @return string $sql
     214 * Filter the get_topics_where portion of the Forums sql when on a user's Replied To page.
     215 *
     216 * This filter is added in bp_has_forum_topics().
     217 *
     218 * @since BuddyPress (1.5.0)
     219 *
     220 * @global object $wpdb The WordPress database global.
     221 *
     222 * @param string $sql SQL fragment.
     223 * @return string $sql SQL fragment.
    201224 */
    202225function bp_forums_add_replied_where_sql( $sql ) {

  • 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.