Skip to:
Content

BuddyPress.org

Changeset 7554


Ignore:
Timestamp:
11/10/2013 02:04:10 AM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-forums component. See #5022

Location:
trunk/bp-forums
Files:
3 edited

Legend:

Unmodified
Added
Removed

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

    r7454 r7554  
    66 * A discussion forums component. Comes bundled with bbPress stand-alone.
    77 *
     8 * Note: The bp-forums component has been retired. Use the bbPress WordPress
     9 * plugin instead.
     10 *
    811 * @package BuddyPress
    9  * @subpackage Forums Core
     12 * @subpackage Forums
    1013 */
    1114
    … …  
    1619
    1720    /**
    18      * Start the forums component creation process
    19      *
    20      * @since BuddyPress (1.5)
     21     * Start the forums component creation process.
     22     *
     23     * @since BuddyPress (1.5.0)
    2124     */
    2225    function __construct() {
    … …  
    3235
    3336    /**
    34      * Setup globals
     37     * Set up bp-forums global settings.
    3538     *
    3639     * The BP_FORUMS_SLUG constant is deprecated, and only used here for
    3740     * backwards compatibility.
    3841     *
    39      * @since BuddyPress (1.5)
     42     * @since BuddyPress (1.5.0)
     43     *
     44     * @see BP_Component::setup_globals() for description of parameters.
     45     *
     46     * @param array $args See {@link BP_Component::setup_globals()}.
    4047     */
    4148    public function setup_globals( $args = array() ) {
    … …  
    6875
    6976    /**
    70      * Include files
     77     * Include bp-forums files.
     78     *
     79     * @see BP_Component::includes() for description of parameters.
     80     *
     81     * @param array $includes See {@link BP_Component::includes()}.
    7182     */
    7283    public function includes( $includes = array() ) {
    … …  
    96107
    97108    /**
    98      * Setup BuddyBar navigation
     109     * Set up component navigation.
     110     *
     111     * @since BuddyPress (1.5.0)
     112     *
     113     * @see BP_Component::setup_nav() for a description of arguments.
     114     *
     115     * @param array $main_nav Optional. See BP_Component::setup_nav() for
     116     *        description.
     117     * @param array $sub_nav Optional. See BP_Component::setup_nav() for
     118     *        description.
    99119     */
    100120    public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
    … …  
    156176
    157177    /**
    158      * Set up the Toolbar
     178     * Set up bp-forums integration with the WordPress admin bar.
     179     *
     180     * @since BuddyPress (1.5.0)
     181     *
     182     * @see BP_Component::setup_admin_bar() for a description of arguments.
     183     *
     184     * @param array $wp_admin_nav See BP_Component::setup_admin_bar()
     185     *        for description.
    159186     */
    160187    public function setup_admin_bar( $wp_admin_nav = array() ) {
    … …  
    203230
    204231    /**
    205      * Sets up the title for pages and <title>
     232     * Set up the title for pages and the <title> element.
    206233     */
    207234    function setup_title() {
    … …  
    226253}
    227254
     255/**
     256 * Set up the bp-forums component.
     257 */
    228258function bp_setup_forums() {
    229259    buddypress()->forums = new BP_Forums_Component();

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

    r7386 r7554  
    11<?php
    22/**
    3  * BuddyPress Forums Screen Functions
     3 * BuddyPress Forums Screen Functions.
    44 *
    55 * @package BuddyPress
    … …  
    1010if ( !defined( 'ABSPATH' ) ) exit;
    1111
     12/**
     13 * Load the Forums directory.
     14 */
    1215function bp_forums_directory_forums_setup() {
    1316
    … …  
    8083add_action( 'bp_screens', 'bp_forums_directory_forums_setup', 2 );
    8184
     85/**
     86 * Load the Topics Started screen.
     87 */
    8288function bp_member_forums_screen_topics() {
    8389    do_action( 'bp_member_forums_screen_topics' );
    … …  
    8692}
    8793
     94/**
     95 * Load the Replied To screen.
     96 */
    8897function bp_member_forums_screen_replies() {
    8998    do_action( 'bp_member_forums_screen_replies' );
    … …  
    93102
    94103/**
    95  * Loads the template content for a user's Favorites forum tab.
     104 * Load the template content for a user's Favorites forum tab.
    96105 *
    97106 * Note that this feature is not fully implemented at the moment.
    98  *
    99  * @package BuddyPress Forums
    100107 */
    101108function bp_member_forums_screen_favorites() {
    … …  
    105112}
    106113
     114/**
     115 * Load a single forum page.
     116 */
    107117function bp_forums_screen_single_forum() {
    108118
    … …  
    116126add_action( 'bp_screens', 'bp_forums_screen_single_forum' );
    117127
     128/**
     129 * Load a single forum topic page.
     130 */
    118131function bp_forums_screen_single_topic() {
    119132
    … …  
    131144
    132145/**
    133  * The main theme compat class for legacy BuddyPress forums, as powered by bbPress 1.x
     146 * The main theme compat class for legacy BuddyPress forums.
    134147 *
    135148 * This class sets up the necessary theme compatability actions to safely output
    136149 * old forum template parts to the_title and the_content areas of a theme.
    137150 *
    138  * @since BuddyPress (1.7)
     151 * @since BuddyPress (1.7.0)
    139152 */
    140153class BP_Forum_Legacy_Theme_Compat {
    141154
    142155    /**
    143      * Setup the old forums component theme compatibility
    144      *
    145      * @since BuddyPress (1.7)
     156     * Set up theme compatibility for the legacy forums component.
     157     *
     158     * @since BuddyPress (1.7.0)
    146159     */
    147160    public function __construct() {
    … …  
    152165     * Are we looking at something that needs old forum theme compatability?
    153166     *
    154      * @since BuddyPress (1.7)
     167     * @since BuddyPress (1.7.0)
    155168     */
    156169    public function is_legacy_forum() {
    … …  
    185198
    186199    /**
    187      * Update the global $post with directory data
    188      *
    189      * @since BuddyPress (1.7)
     200     * Update the global $post with directory data.
     201     *
     202     * @since BuddyPress (1.7.0)
    190203     */
    191204    public function directory_dummy_post() {
    … …  
    212225
    213226    /**
    214      * Filter the_content with the old forum index template part
    215      *
    216      * @since BuddyPress (1.7)
     227     * Filter the_content with the old forum index template part.
     228     *
     229     * @since BuddyPress (1.7.0)
    217230     */
    218231    public function directory_content() {

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

    r7513 r7554  
    11<?php
    22/**
    3  * BuddyPress Forums Template Tags
     3 * BuddyPress Forums Template Tags.
    44 *
    55 * @package BuddyPress
    … …  
    1111
    1212/**
    13  * Output the forums component slug
    14  *
    15  * @package BuddyPress
    16  * @subpackage Forums Template
    17  * @since BuddyPress (1.5)
     13 * Output the forums component slug.
     14 *
     15 * @since BuddyPress (1.5.0)
    1816 *
    1917 * @uses bp_get_forums_slug()
    … …  
    2321}
    2422    /**
    25      * Return the forums component slug
    26      *
    27      * @package BuddyPress
    28      * @subpackage Forums Template
    29      * @since BuddyPress (1.5)
     23     * Return the forums component slug.
     24     *
     25     * @since BuddyPress (1.5.0)
     26     *
     27     * @return string Slug for the forums component.
    3028     */
    3129    function bp_get_forums_slug() {
    … …  
    3533
    3634/**
    37  * Output the forums component root slug
    38  *
    39  * @package BuddyPress
    40  * @subpackage Forums Template
    41  * @since BuddyPress (1.5)
     35 * Output the forums component root slug.
     36 *
     37 * @since BuddyPress (1.5.0)
    4238 *
    4339 * @uses bp_get_forums_root_slug()
    … …  
    4743}
    4844    /**
    49      * Return the forums component root slug
    50      *
    51      * @package BuddyPress
    52      * @subpackage Forums Template
    53      * @since BuddyPress (1.5)
     45     * Return the forums component root slug.
     46     *
     47     * @since BuddyPress (1.5.0)
     48     *
     49     * @return string Root slug for the forums component.
    5450     */
    5551    function bp_get_forums_root_slug() {
    … …  
    5955
    6056/**
    61  * Output forum directory permalink
    62  *
    63  * @package BuddyPress
    64  * @subpackage Forums Template
    65  * @since BuddyPress (1.5)
     57 * Output permalink for the forum directory.
     58 *
     59 * @since BuddyPress (1.5.0)
     60 *
    6661 * @uses bp_get_forums_directory_permalink()
    6762 */
    … …  
    7065}
    7166    /**
    72      * Return forum directory permalink
    73      *
    74      * @package BuddyPress
    75      * @subpackage Forums Template
    76      * @since BuddyPress (1.5)
     67     * Return permalink for the forum directory.
     68     *
     69     * @since BuddyPress (1.5.0)
     70     *
    7771     * @uses apply_filters()
    7872     * @uses traisingslashit()
    7973     * @uses bp_get_root_domain()
    8074     * @uses bp_get_forums_root_slug()
    81      * @return string
     75     *
     76     * @return string The permalink for the forums component directory.
    8277     */
    8378    function bp_get_forums_directory_permalink() {
    … …  
    8580    }
    8681
     82/**
     83 * The main forums template loop class.
     84 *
     85 * Responsible for loading a group of forum topics into a loop for display.
     86 */
    8787class BP_Forums_Template_Forum {
     88    /**
     89     * The loop iterator.
     90     *
     91     * @access public
     92     * @var int
     93     */
    8894    var $current_topic = -1;
     95
     96    /**
     97     * The number of topics returned by the paged query.
     98     *
     99     * @access public
     100     * @var int
     101     */
    89102    var $topic_count;
     103
     104    /**
     105     * Array of topics located by the query.
     106     *
     107     * @access public
     108     * @var array
     109     */
    90110    var $topics;
     111
     112    /**
     113     * The topic object currently being iterated on.
     114     *
     115     * @access public
     116     * @var object
     117     */
    91118    var $topic;
    92119
     120    /**
     121     * The ID of the forum whose topics are being queried.
     122     *
     123     * @access public
     124     * @var int
     125     */
    93126    var $forum_id;
    94127
     128    /**
     129     * A flag for whether the loop is currently being iterated.
     130     *
     131     * @access public
     132     * @var bool
     133     */
    95134    var $in_the_loop;
    96135
     136    /**
     137     * The page number being requested.
     138     *
     139     * @access public
     140     * @var public
     141     */
    97142    var $pag_page;
     143
     144    /**
     145     * The number of items being requested per page.
     146     *
     147     * @access public
     148     * @var public
     149     */
    98150    var $pag_num;
     151
     152    /**
     153     * An HTML string containing pagination links.
     154     *
     155     * @access public
     156     * @var string
     157     */
    99158    var $pag_links;
     159
     160    /**
     161     * The total number of topics matching the query parameters.
     162     *
     163     * @access public
     164     * @var int
     165     */
    100166    var $total_topic_count;
    101167
     168    /**
     169     * Whether requesting a single topic. Not currently used.
     170     *
     171     * @access public
     172     * @var bool
     173     */
    102174    var $single_topic = false;
    103175
     176    /**
     177     * Term to sort by. Not currently used.
     178     *
     179     * @access public
     180     * @var string
     181     */
    104182    var $sort_by;
     183
     184    /**
     185     * Sort order. Not currently used.
     186     *
     187     * @access public
     188     * @var string
     189     */
    105190    var $order;
    106191
     192    /**
     193     * Constructor method.
     194     *
     195     * @param string $type The 'type' is the sort order/kind. 'newest',
     196     *        'popular', 'unreplied', 'tags'.
     197     * @param int $forum_id The ID of the forum for which topics are being
     198     *        queried.
     199     * @param int $user_id The ID of the user to whom topics should be
     200     *        limited. Pass false to remove this filter.
     201     * @param int $page The number of the page being requested.
     202     * @param int $per_page The number of items being requested perpage.
     203     * @param string $no_stickies Requested sticky format.
     204     * @param string $search_terms Filter results by a string.
     205     * @param int $offset Optional. Offset results by a given numeric value.
     206     * @param int $number Optional. Total number of items to retrieve.
     207     */
    107208    function __construct( $type, $forum_id, $user_id, $page, $per_page, $max, $no_stickies, $search_terms, $offset = false, $number = false ) {
    108209        global $bp;
    … …  
    200301    }
    201302
     303    /**
     304     * Whether there are topics available in the loop.
     305     *
     306     * @see bp_has_forum_topics()
     307     *
     308     * @return bool True if there are items in the loop, otherwise false.
     309     */
    202310    function has_topics() {
    203311        if ( $this->topic_count )
    … …  
    207315    }
    208316
     317    /**
     318     * Set up the next topic and iterate index.
     319     *
     320     * @return object The next topic to iterate over.
     321     */
    209322    function next_topic() {
    210323        $this->current_topic++;
    … …  
    214327    }
    215328
     329    /**
     330     * Rewind the topics and reset topic index.
     331     */
    216332    function rewind_topics() {
    217333        $this->current_topic = -1;
    … …  
    221337    }
    222338
     339    /**
     340     * Whether there are blogs left in the loop to iterate over.
     341     *
     342     * This method is used by {@link bp_forum_topics()} as part of the while loop
     343     * that controls iteration inside the blogs loop, eg:
     344     *     while ( bp_forum_topics() ) { ...
     345     *
     346     * @see bp_forum_topics()
     347     *
     348     * @return bool True if there are more topics to show, otherwise false.
     349     */
    223350    function user_topics() {
    224351        if ( $this->current_topic + 1 < $this->topic_count ) {
    … …  
    234361    }
    235362
     363    /**
     364     * Set up the current topic in the loop.
     365     *
     366     * @see bp_the_forum_topic()
     367     */
    236368    function the_topic() {
    237369        global $topic;
    … …  
    249381 * Initiate the forum topics loop.
    250382 *
    251  * Like other BuddyPress custom loops, the default arguments for this function are determined
    252  * dynamically, depending on your current page. All of these $defaults can be overridden in the
    253  * $args parameter.
    254  *
    255  * @package BuddyPress
    256  * @uses apply_filters() Filter bp_has_topics to manipulate the $forums_template global before
    257  *   it's rendered, or to modify the value of has_topics().
    258  *
    259  * @param array $args See inline definition of $defaults for explanation of arguments
    260  * @return bool Returns true when forum topics are found corresponding to the args, false otherwise.
     383 * Like other BuddyPress custom loops, the default arguments for this function
     384 * are determined dynamically, depending on your current page. All of these
     385 * $defaults can be overridden in the $args parameter.
     386 *
     387 * @uses apply_filters() Filter 'bp_has_topics' to manipulate the
     388 *       $forums_template global before it's rendered, or to modify the value
     389 *       of has_topics().
     390 *
     391 * @param array $args {
     392 *     Arguments for limiting the contents of the forum topics loop.
     393 *
     394 *     @type string $type The 'type' is the sort order/kind. 'newest',
     395 *           'popular', 'unreplied', 'tags'. Default: 'newest'.
     396 *     @type int $forum_id The ID of the forum for which topics are being
     397 *           queried. Default: the ID of the forum belonging to the current
     398 *           group, if available.
     399 *     @type int $user_id The ID of a user to whom to limit results. If viewing
     400 *           a member's profile, defaults to that member's ID; otherwise
     401 *           defaults to 0.
     402 *     @type int $page The number of the page being requested. Default: 1, or
     403 *           the value of $_GET['p'].
     404 *     @type int $per_pag The number items to return per page. Default: 20, or
     405 *           the value of $_GET['n'].
     406 *     @type int $max Optional. Max records to return. Default: false (no max).
     407 *     @type int $number Optional. Number of records to return. Default: false.
     408 *     @type int $offset Optional. Offset results by a given value.
     409 *           Default: false.
     410 *     @type string $search_terms Optional. A string to which results should be
     411 *           limited. Default: false, or the value of $_GET['fs'].
     412 *     @type string|bool $do_stickies Whether to move stickies to the top of
     413 *           the sort order. Default: true if looking at a group forum,
     414 *           otherwise false.
     415 * }
     416 * @return bool True when forum topics are found corresponding to the args,
     417 *         false otherwise.
    261418 */
    262419function bp_has_forum_topics( $args = '' ) {
    … …  
    426583}
    427584
     585/**
     586 * Determine whether there are still topics left in the loop.
     587 *
     588 * @global BP_Forums_Template_Forum $forum_template Template global.
     589 *
     590 * @return bool Returns true when topics are found.
     591 */
    428592function bp_forum_topics() {
    429593    global $forum_template;
    … …  
    431595}
    432596
     597/**
     598 * Get the current topic object in the loop.
     599 *
     600 * @global BP_Forums_Template_Forum $forum_template Template global.
     601 *
     602 * @return object The current topic object.
     603 */
    433604function bp_the_forum_topic() {
    434605    global $forum_template;
    … …  
    436607}
    437608
     609/**
     610 * Output the ID of the current topic in the loop.
     611 */
    438612function bp_the_topic_id() {
    439613    echo bp_get_the_topic_id();
    440614}
     615    /**
     616     * Return the ID of the current topic in the loop.
     617     *
     618     * @return int ID of the current topic in the loop.
     619     */
    441620    function bp_get_the_topic_id() {
    442621        global $forum_template;
    … …  
    445624    }
    446625
     626/**
     627 * Output the title of the current topic in the loop.
     628 */
    447629function bp_the_topic_title() {
    448630    echo bp_get_the_topic_title();
    449631}
     632    /**
     633     * Return the title of the current topic in the loop.
     634     *
     635     * @return string Title of the current topic in the loop.
     636     */
    450637    function bp_get_the_topic_title() {
    451638        global $forum_template;
    … …  
    454641    }
    455642
     643/**
     644 * Output the slug of the current topic in the loop.
     645 */
    456646function bp_the_topic_slug() {
    457647    echo bp_get_the_topic_slug();
    458648}
     649    /**
     650     * Return the slug of the current topic in the loop.
     651     *
     652     * @return string Slug of the current topic in the loop.
     653     */
    459654    function bp_get_the_topic_slug() {
    460655        global $forum_template;
    … …  
    463658    }
    464659
     660/**
     661 * Output the text of the first post in the current topic in the loop.
     662 */
    465663function bp_the_topic_text() {
    466664    echo bp_get_the_topic_text();
    467665}
     666    /**
     667     * Return the text of the first post in the current topic in the loop.
     668     *
     669     * @return string Text of the first post in the current topic.
     670     */
    468671    function bp_get_the_topic_text() {
    469672        global $forum_template;
    … …  
    473676    }
    474677
     678/**
     679 * Output the ID of the user who posted the current topic in the loop.
     680 */
    475681function bp_the_topic_poster_id() {
    476682    echo bp_get_the_topic_poster_id();
    477683}
     684    /**
     685     * Return the ID of the user who posted the current topic in the loop.
     686     *
     687     * @return int ID of the user who posted the current topic.
     688     */
    478689    function bp_get_the_topic_poster_id() {
    479690        global $forum_template;
    … …  
    482693    }
    483694
     695/**
     696 * Output the avatar of the user who posted the current topic in the loop.
     697 *
     698 * @see bp_get_the_topic_poster_avatar() for a description of arguments.
     699 *
     700 * @param array $args See {@link bp_get_the_topic_poster_avatar()}.
     701 */
    484702function bp_the_topic_poster_avatar( $args = '' ) {
    485703    echo bp_get_the_topic_poster_avatar( $args );
    486704}
     705    /**
     706     * Return the avatar of the user who posted the current topic in the loop.
     707     *
     708     * @param array $args {
     709     *     Arguments for building the avatar.
     710     *     @type string $type Avatar type. 'thumb' or 'full'. Default:
     711     *           'thumb'.
     712     *     @type int $width Width of the avatar, in pixels. Default: the
     713     *           width corresponding to $type.
     714     *           See {@link bp_core_fetch_avatar()}.
     715     *     @type int $height Height of the avatar, in pixels. Default: the
     716     *           height corresponding to $type.
     717     *           See {@link bp_core_fetch_avatar()}.
     718     *     @type string $alt The text of the image's 'alt' attribute.
     719     *           Default: 'Profile picture of [user name]'.
     720     * }
     721     * @return string HTML of user avatar.
     722     */
    487723    function bp_get_the_topic_poster_avatar( $args = '' ) {
    488724        global $forum_template;
    … …  
    501737    }
    502738
     739/**
     740 * Output the name of the user who posted the current topic in the loop.
     741 */
    503742function bp_the_topic_poster_name() {
    504743    echo bp_get_the_topic_poster_name();
    505744}
     745    /**
     746     * Return the name of the user who posted the current topic in the loop.
     747     *
     748     * @return string Name of the user who posted the current topic.
     749     */
    506750    function bp_get_the_topic_poster_name() {
    507751        global $forum_template;
    … …  
    515759    }
    516760
     761/**
     762 * Output the ID of the object associated with the current topic in the loop.
     763 */
    517764function bp_the_topic_object_id() {
    518765    echo bp_get_the_topic_object_id();
    519766}
     767    /**
     768     * Return the ID of the object associated with the current topic in the loop.
     769     *
     770     * Objects are things like associated groups.
     771     *
     772     * @return int ID of the associated object.
     773     */
    520774    function bp_get_the_topic_object_id() {
    521775        global $forum_template;
    … …  
    524778    }
    525779
     780/**
     781 * Output the name of the object associated with the current topic in the loop.
     782 */
    526783function bp_the_topic_object_name() {
    527784    echo bp_get_the_topic_object_name();
    528785}
     786    /**
     787     * Return the name of the object associated with the current topic in the loop.
     788     *
     789     * Objects are things like groups. So this function would return the
     790     * name of the group associated with the forum topic, if it exists.
     791     *
     792     * @return string Object name.
     793     */
    529794    function bp_get_the_topic_object_name() {
    530795        global $forum_template;
    … …  
    538803    }
    539804
     805/**
     806 * Output the slug of the object associated with the current topic in the loop.
     807 */
    540808function bp_the_topic_object_slug() {
    541809    echo bp_get_the_topic_object_slug();
    542810}
     811    /**
     812     * Return the slug of the object associated with the current topic in the loop.
     813     *
     814     * Objects are things like groups. So this function would return the
     815     * slug of the group associated with the forum topic, if it exists.
     816     *
     817     * @return string Object slug.
     818     */
    543819    function bp_get_the_topic_object_slug() {
    544820        global $forum_template;
    … …  
    547823    }
    548824
     825/**
     826 * Output the permalink of the object associated with the current topic in the loop.
     827 */
    549828function bp_the_topic_object_permalink() {
    550829    echo bp_get_the_topic_object_permalink();
    551830}
     831    /**
     832     * Return the permalink of the object associated with the current topic in the loop.
     833     *
     834     * Objects are things like groups. So this function would return the
     835     * permalink of the group associated with the forum topic, if it exists.
     836     *
     837     * @return string Object permalink.
     838     */
    552839    function bp_get_the_topic_object_permalink() {
    553840
    … …  
    561848    }
    562849
     850/**
     851 * Output the linked name of the user who last posted to the current topic in the loop.
     852 */
    563853function bp_the_topic_last_poster_name() {
    564854    echo bp_get_the_topic_last_poster_name();
    565855}
     856    /**
     857     * Return the linked name of the user who last posted to the current topic in the loop.
     858     *
     859     * @return string HTML link to the profile of the user who last posted
     860     *         to the current topic.
     861     */
    566862    function bp_get_the_topic_last_poster_name() {
    567863        global $forum_template;
    … …  
    577873    }
    578874
     875/**
     876 * Output the permalink of the object associated with the current topic in the loop.
     877 *
     878 * @see bp_get_the_topic_object_avatar() for description of arguments.
     879 *
     880 * @param array $args See {@bp_get_the_topic_object_avatar()}.
     881 */
    579882function bp_the_topic_object_avatar( $args = '' ) {
    580883    echo bp_get_the_topic_object_avatar( $args );
    581884}
     885    /**
     886     * Return the avatar of the object associated with the current topic in the loop.
     887     *
     888     * Objects are things like groups. So this function would return the
     889     * avatar of the group associated with the forum topic, if it exists.
     890     *
     891     * @param array $args {
     892     *     Arguments for building the avatar.
     893     *     @type string $type Avatar type. 'thumb' or 'full'. Default:
     894     *           'thumb'.
     895     *     @type int $width Width of the avatar, in pixels. Default: the
     896     *           width corresponding to $type.
     897     *           See {@link bp_core_fetch_avatar()}.
     898     *     @type int $height Height of the avatar, in pixels. Default:
     899     *           the height corresponding to $type.
     900     *           See {@link bp_core_fetch_avatar()}.
     901     *     @type string $alt The text of the image's 'alt' attribute.
     902     *           Default: 'Group logo for [group name]'.
     903     * }
     904     * @return string Object avatar.
     905     */
    582906    function bp_get_the_topic_object_avatar( $args = '' ) {
    583907        global $forum_template;
    … …  
    599923    }
    600924
     925/**
     926 * Output the avatar for the user who last posted to the current topic in the loop.
     927 *
     928 * @see bp_get_the_topic_last_poster_avatar() for description of arguments.
     929 *
     930 * @param array $args See {@bp_get_the_topic_last_poster_avatar()}.
     931 */
    601932function bp_the_topic_last_poster_avatar( $args = '' ) {
    602933    echo bp_get_the_topic_last_poster_avatar( $args );
    603934}
     935    /**
     936     * Return the avatar for the user who last posted to the current topic in the loop.
     937     *
     938     * @param array $args {
     939     *     Arguments for building the avatar.
     940     *     @type string $type Avatar type. 'thumb' or 'full'. Default:
     941     *           'thumb'.
     942     *     @type int $width Width of the avatar, in pixels. Default: the
     943     *           width corresponding to $type.
     944     *           See {@link bp_core_fetch_avatar()}.
     945     *     @type int $height Height of the avatar, in pixels. Default:
     946     *           the height corresponding to $type.
     947     *           See {@link bp_core_fetch_avatar()}.
     948     *     @type string $alt The text of the image's 'alt' attribute.
     949     *           Default: 'Profile picture of [group name]'.
     950     * }
     951     * @return string User avatar.
     952     */
    604953    function bp_get_the_topic_last_poster_avatar( $args = '' ) {
    605954        global $forum_template;
    … …  
    618967    }
    619968
     969/**
     970 * Output the start time of the current topic in the loop.
     971 */
    620972function bp_the_topic_start_time() {
    621973    echo bp_get_the_topic_start_time();
    622974}
     975    /**
     976     * Return the start time of the current topic in the loop.
     977     *
     978     * @return string Start time of the current topic.
     979     */
    623980    function bp_get_the_topic_start_time() {
    624981        global $forum_template;
    … …  
    627984    }
    628985
     986/**
     987 * Output the topic time of the current topic in the loop.
     988 */
    629989function bp_the_topic_time() {
    630990    echo bp_get_the_topic_time();
    631991}
     992    /**
     993     * Return the topic time of the current topic in the loop.
     994     *
     995     * @return string Topic time of the current topic.
     996     */
    632997    function bp_get_the_topic_time() {
    633998        global $forum_template;
    … …  
    6361001    }
    6371002
     1003/**
     1004 * Output the ID of the forum associated with the current topic in the loop.
     1005 */
    6381006function bp_the_topic_forum_id() {
    6391007    echo bp_get_the_topic_forum_id();
    6401008}
     1009    /**
     1010     * Return the ID of the forum associated with the current topic in the loop.
     1011     *
     1012     * @return int ID of the forum associated with the current topic.
     1013     */
    6411014    function bp_get_the_topic_forum_id() {
    6421015        global $forum_template;
    … …  
    6451018    }
    6461019
     1020/**
     1021 * Output the status of the current topic in the loop.
     1022 */
    6471023function bp_the_topic_status() {
    6481024    echo bp_get_the_topic_status();
    6491025}
     1026    /**
     1027     * Return the status of the current topic in the loop.
     1028     *
     1029     * @return string Status of the current topic.
     1030     */
    6501031    function bp_get_the_topic_status() {
    6511032        global $forum_template;
    … …  
    6541035    }
    6551036
     1037/**
     1038 * Output whether the current topic in the loop is open.
     1039 */
    6561040function bp_the_topic_is_topic_open() {
    6571041    echo bp_get_the_topic_is_topic_open();
    6581042}
     1043    /**
     1044     * Return whether the current topic in the loop is open.
     1045     *
     1046     * @return unknown
     1047     */
    6591048    function bp_get_the_topic_is_topic_open() {
    6601049        global $forum_template;
    … …  
    6631052    }
    6641053
     1054/**
     1055 * Output the ID of the last post in the current topic in the loop.
     1056 */
    6651057function bp_the_topic_last_post_id() {
    6661058    echo bp_get_the_topic_last_post_id();
    6671059}
     1060    /**
     1061     * Return the ID of the last post in the current topic in the loop.
     1062     *
     1063     * @return int ID of the last post in the current topic.
     1064     */
    6681065    function bp_get_the_topic_last_post_id() {
    6691066        global $forum_template;
    … …  
    6721069    }
    6731070
     1071/**
     1072 * Output whether the current topic in the loop is sticky.
     1073 */
    6741074function bp_the_topic_is_sticky() {
    6751075    echo bp_get_the_topic_is_sticky();
    6761076}
     1077    /**
     1078     * Return whether the current topic in the loop is sticky.
     1079     *
     1080     * @return unknown
     1081     */
    6771082    function bp_get_the_topic_is_sticky() {
    6781083        global $forum_template;
    … …  
    6811086    }
    6821087
     1088/**
     1089 * Output a 'x posts' string with the number of posts in the current topic.
     1090 */
    6831091function bp_the_topic_total_post_count() {
    6841092    echo bp_get_the_topic_total_post_count();
    6851093}
     1094    /**
     1095     * Return a 'x posts' string with the number of posts in the current topic.
     1096     *
     1097     * @return string String of the form 'x posts'.
     1098     */
    6861099    function bp_get_the_topic_total_post_count() {
    6871100        global $forum_template;
    … …  
    6931106    }
    6941107
     1108/**
     1109 * Output the total number of posts in the current topic in the loop.
     1110 */
    6951111function bp_the_topic_total_posts() {
    6961112    echo bp_get_the_topic_total_posts();
    6971113}
     1114    /**
     1115     * Return the total number of posts in the current topic in the loop.
     1116     *
     1117     * @return int Total number of posts in the current topic.
     1118     */
    6981119    function bp_get_the_topic_total_posts() {
    6991120        global $forum_template;
    … …  
    7021123    }
    7031124
     1125/**
     1126 * Output the tag count for the current topic in the loop.
     1127 */
    7041128function bp_the_topic_tag_count() {
    7051129    echo bp_get_the_topic_tag_count();
    7061130}
     1131    /**
     1132     * Return the tag count for the current topic in the loop.
     1133     *
     1134     * @return int Tag count for the current topic.
     1135     */
    7071136    function bp_get_the_topic_tag_count() {
    7081137        global $forum_template;
    … …  
    7111140    }
    7121141
     1142/**
     1143 * Output the permalink of the current topic in the loop.
     1144 */
    7131145function bp_the_topic_permalink() {
    7141146    echo bp_get_the_topic_permalink();
    7151147}
     1148    /**
     1149     * Return the permalink for the current topic in the loop.
     1150     *
     1151     * @return string Permalink for the current topic.
     1152     */
    7161153    function bp_get_the_topic_permalink() {
    7171154        global $forum_template, $bp;
    … …  
    7371174    }
    7381175
     1176/**
     1177 * Output a 'since' string describing when the current topic was created.
     1178 */
    7391179function bp_the_topic_time_since_created() {
    7401180    echo bp_get_the_topic_time_since_created();
    7411181}
     1182    /**
     1183     * Return a 'since' string describing when the current topic was created.
     1184     *
     1185     * @see bp_core_time_since() for a description of return value.
     1186     *
     1187     * @return string
     1188     */
    7421189    function bp_get_the_topic_time_since_created() {
    7431190        global $forum_template;
    … …  
    7461193    }
    7471194
     1195/**
     1196 * Output an excerpt from the latest post of the current topic in the loop.
     1197 */
    7481198function bp_the_topic_latest_post_excerpt( $args = '' ) {
    7491199    echo bp_get_the_topic_latest_post_excerpt( $args );
    7501200}
     1201    /**
     1202     * Return an excerpt from the latest post of the current topic in the loop.
     1203     *
     1204     * @param array $args {
     1205     *     @type int $length The length of the excerpted text. Default: 225.
     1206     * }
     1207     * @return string Post excerpt.
     1208     */
    7511209    function bp_get_the_topic_latest_post_excerpt( $args = '' ) {
    7521210        global $forum_template;
    … …  
    7651223    }
    7661224
     1225/**
     1226 * Output a 'since' string describing when the last post in the current topic was created.
     1227 */
    7671228function bp_the_topic_time_since_last_post() {
    7681229    echo bp_get_the_topic_time_since_last_post();
    7691230}
     1231    /**
     1232     * Return a 'since' string describing when the last post in the current topic was created.
     1233     *
     1234     * @see bp_core_time_since() for a description of return value.
     1235     *
     1236     * @return string
     1237     */
    7701238    function bp_get_the_topic_time_since_last_post() {
    7711239        global $forum_template;
    … …  
    7741242    }
    7751243
     1244/**
     1245 * Output whether the current topic in the loop belongs to the logged-in user.
     1246 */
    7761247function bp_the_topic_is_mine() {
    7771248    echo bp_get_the_topic_is_mine();
    7781249}
     1250    /**
     1251     * Does the current topic belong to the logged-in user?
     1252     *
     1253     * @return bool True if the current topic in the loop was created by
     1254     *         the logged-in user, otherwise false.
     1255     */
    7791256    function bp_get_the_topic_is_mine() {
    7801257        global $forum_template;
    … …  
    7831260    }
    7841261
     1262/**
     1263 * Output the admin links for the current topic in the loop.
     1264 *
     1265 * @see bp_get_the_topic_admin_links() for a description of arguments.
     1266 *
     1267 * @param array $args See {@link bp_get_the_topic_admin_links()}.
     1268 */
    7851269function bp_the_topic_admin_links( $args = '' ) {
    7861270    echo bp_get_the_topic_admin_links( $args );
    7871271}
     1272    /**
     1273     * Return the admin links for the current topic in the loop.
     1274     *
     1275     * @param array $args {
     1276     *     @type string $seperator The character to use when separating
     1277     *           links. Default: '|'.
     1278     * }
     1279     * @return HTML string containing the admin links for the current topic.
     1280     */
    7881281    function bp_get_the_topic_admin_links( $args = '' ) {
    7891282        global $forum_template;
    … …  
    8151308    }
    8161309
     1310/**
     1311 * Output the CSS class for the current topic in the loop.
     1312 */
    8171313function bp_the_topic_css_class() {
    8181314    echo bp_get_the_topic_css_class();
    8191315}
    820 
     1316    /**
     1317     * Return the CSS class for the current topic in the loop.
     1318     *
     1319     * This class may contain keywords like 'alt', 'sticky', or 'closed',
     1320     * based on context.
     1321     *
     1322     * @return string Contents of the 'class' attribute.
     1323     */
    8211324    function bp_get_the_topic_css_class() {
    8221325        global $forum_template;
    … …  
    8361339    }
    8371340
     1341/**
     1342 * Output the permalink to the 'personal' topics tab.
     1343 */
    8381344function bp_my_forum_topics_link() {
    8391345    echo bp_get_my_forum_topics_link();
    8401346}
     1347    /**
     1348     * Return the permalink to the 'personal' topics tab.
     1349     *
     1350     * @return string Link to the 'personal' topics tab.
     1351     */
    8411352    function bp_get_my_forum_topics_link() {
    8421353        global $bp;
    … …  
    8451356    }
    8461357
     1358/**
     1359 * Output the permalink to the 'unreplied' topics tab.
     1360 */
    8471361function bp_unreplied_forum_topics_link() {
    8481362    echo bp_get_unreplied_forum_topics_link();
    8491363}
     1364    /**
     1365     * Return the permalink to the 'unreplied' topics tab.
     1366     *
     1367     * @return string Link to the 'unreplied' topics tab.
     1368     */
    8501369    function bp_get_unreplied_forum_topics_link() {
    8511370        global $bp;
    … …  
    8541373    }
    8551374
    856 
     1375/**
     1376 * Output the permalink to the 'popular' topics tab.
     1377 */
    8571378function bp_popular_forum_topics_link() {
    8581379    echo bp_get_popular_forum_topics_link();
    8591380}
     1381    /**
     1382     * Return the permalink to the 'popular' topics tab.
     1383     *
     1384     * @return string Link to the 'popular' topics tab.
     1385     */
    8601386    function bp_get_popular_forum_topics_link() {
    8611387        global $bp;
    … …  
    8641390    }
    8651391
     1392/**
     1393 * Output the link to the forums directory.
     1394 */
    8661395function bp_newest_forum_topics_link() {
    8671396    echo bp_get_newest_forum_topics_link();
    8681397}
     1398    /**
     1399     * Return the link to the forums directory.
     1400     *
     1401     * @return string Link to the forums directory.
     1402     */
    8691403    function bp_get_newest_forum_topics_link() {
    8701404        global $bp;
    … …  
    8731407    }
    8741408
     1409/**
     1410 * Output the currently viewed topic list type.
     1411 */
    8751412function bp_forum_topic_type() {
    8761413    echo bp_get_forum_topic_type();
    8771414}
     1415    /**
     1416     * Return the currently viewed topic list type.
     1417     *
     1418     * Eg, 'newest', 'popular', etc.
     1419     *
     1420     * @return string Type of the currently viewed topic list.
     1421     */
    8781422    function bp_get_forum_topic_type() {
    8791423        global $bp;
    … …  
    8861430
    8871431/**
    888  * Echoes the output of bp_get_forum_topic_new_reply_link()
    889  *
    890  * @package BuddyPress
    891  * @since BuddyPress (1.5)
     1432 * Output the value of bp_get_forum_topic_new_reply_link().
     1433 *
     1434 * @since BuddyPress (1.5.0)
    8921435 */
    8931436function bp_forum_topic_new_reply_link() {
    … …  
    8951438}
    8961439    /**
    897      * Returns the permalink for the New Reply button at the top of forum topics
    898      *
    899      * @package BuddyPress
    900      * @since BuddyPress (1.5)
    901      *
    902      * @uses apply_filters() Filter bp_get_forum_topic_new_reply_link to modify
    903      * @return string The URL for the New Reply link
     1440     * Return the permalink for the New Reply button at the top of forum topics.
     1441     *
     1442     * @since BuddyPress (1.5.0)
     1443     *
     1444     * @uses apply_filters() Filter bp_get_forum_topic_new_reply_link to
     1445     *       modify.
     1446     * @return string The URL for the New Reply link.
    9041447     */
    9051448    function bp_get_forum_topic_new_reply_link() {
    … …  
    9221465
    9231466/**
    924  * Echoes the output of bp_get_forums_tag_name()
    925  *
    926  * @package BuddyPress
     1467 * Output the currently viewed tag name.
     1468 *
    9271469 * @todo Deprecate?
    9281470 */
    … …  
    9311473}
    9321474    /**
    933      * Outputs the currently viewed tag name
    934      *
    935      * @package BuddyPress
     1475     * Return the currently viewed tag name.
     1476     *
    9361477     * @todo Deprecate? Seems unused
    9371478     */
    … …  
    9421483    }
    9431484
     1485/**
     1486 * Output the pagination links for the current topic list.
     1487 */
    9441488function bp_forum_pagination() {
    9451489    echo bp_get_forum_pagination();
    9461490}
     1491    /**
     1492     * Return the pagination links for the current topic list.
     1493     *
     1494     * @return string HTML pagination links.
     1495     */
    9471496    function bp_get_forum_pagination() {
    9481497        global $forum_template;
    … …  
    9511500    }
    9521501
     1502/**
     1503 * Output the pagination count for the current topic list.
     1504 */
    9531505function bp_forum_pagination_count() {
    9541506    echo bp_get_forum_pagination_count();
    9551507}
     1508    /**
     1509     * Return the pagination count for the current topic list.
     1510     *
     1511     * The "count" is a string of the form "Viewing x of y topics".
     1512     *
     1513     * @return string
     1514     */
    9561515    function bp_get_forum_pagination_count() {
    9571516        global $bp, $forum_template;
    … …  
    9691528    }
    9701529
     1530/**
     1531 * Are we currently on an Edit Topic screen?
     1532 *
     1533 * @return bool True if currently editing a topic, otherwise false.
     1534 */
    9711535function bp_is_edit_topic() {
    9721536    global $bp;
    … …  
    9781542}
    9791543
     1544/**
     1545 * The single forum topic template loop class.
     1546 *
     1547 * Responsible for loading a topic's posts into a loop for display.
     1548 */
    9801549class BP_Forums_Template_Topic {
     1550    /**
     1551     * The loop iterator.
     1552     *
     1553     * @access public
     1554     * @var int
     1555     */
    9811556    var $current_post = -1;
     1557
     1558    /**
     1559     * The number of posts returned by the paged query.
     1560     *
     1561     * @access public
     1562     * @var int
     1563     */
    9821564    var $post_count;
     1565
     1566    /**
     1567     * Array of posts located by the query.
     1568     *
     1569     * @access public
     1570     * @var array
     1571     */
    9831572    var $posts;
     1573
     1574    /**
     1575     * The post object currently being iterated on.
     1576     *
     1577     * @access public
     1578     * @var object
     1579     */
    9841580    var $post;
    9851581
     1582    /**
     1583     * The ID of the forum whose topic is being queried.
     1584     *
     1585     * @access public
     1586     * @var int
     1587     */
    9861588    var $forum_id;
     1589
     1590    /**
     1591     * The ID of the topic whose posts are being queried.
     1592     *
     1593     * @access public
     1594     * @var int
     1595     */
    9871596    var $topic_id;
     1597
     1598    /**
     1599     * The topic object to which the posts belong.
     1600     *
     1601     * @access public
     1602     * @var object
     1603     */
    9881604    var $topic;
    9891605
     1606    /**
     1607     * A flag for whether the loop is currently being iterated.
     1608     *
     1609     * @access public
     1610     * @var bool
     1611     */
    9901612    var $in_the_loop;
    9911613
    9921614    /**
    993      * Contains a 'total_pages' property holding total number of pages in this loop.
    994      *
    995      * @since BuddyPress (1.2)
     1615     * Contains a 'total_pages' property holding total number of pages in
     1616     * this loop.
     1617     *
     1618     * @since BuddyPress (1.2.0)
    9961619     * @var stdClass
    9971620     */
    9981621    public $pag;
    9991622
     1623    /**
     1624     * The page number being requested.
     1625     *
     1626     * @access public
     1627     * @var public
     1628     */
    10001629    var $pag_page;
     1630
     1631    /**
     1632     * The number of items being requested per page.
     1633     *
     1634     * @access public
     1635     * @var public
     1636     */
    10011637    var $pag_num;
     1638
     1639    /**
     1640     * An HTML string containing pagination links.
     1641     *
     1642     * @access public
     1643     * @var string
     1644     */
    10021645    var $pag_links;
     1646
     1647    /**
     1648     * The total number of posts matching the query parameters.
     1649     *
     1650     * @access public
     1651     * @var int
     1652     */
    10031653    var $total_post_count;
    10041654
     1655    /**
     1656     * Whether requesting a single topic. Not currently used.
     1657     *
     1658     * @access public
     1659     * @var bool
     1660     */
    10051661    var $single_post = false;
    10061662
     1663    /**
     1664     * Term to sort by.
     1665     *
     1666     * @access public
     1667     * @var string
     1668     */
    10071669    var $sort_by;
     1670
     1671    /**
     1672     * Sort order.
     1673     *
     1674     * @access public
     1675     * @var string
     1676     */
    10081677    var $order;
    10091678
     1679    /**
     1680     * Constructor method.
     1681     *
     1682     * @param int $topic_id ID of the topic whose posts are being requested.
     1683     * @param int $per_page Number of items to return per page.
     1684     * @param int $max Max records to return.
     1685     * @param string $order Direction to order results.
     1686     */
    10101687    function __construct( $topic_id, $per_page, $max, $order ) {
    10111688        global $bp, $current_user, $forum_template;
    … …  
    10681745    }
    10691746
     1747    /**
     1748     * Whether there are posts available in the loop.
     1749     *
     1750     * @see bp_has_forum_topic_posts()
     1751     *
     1752     * @return bool True if there are items in the loop, otherwise false.
     1753     */
    10701754    function has_posts() {
    10711755        if ( $this->post_count )
    … …  
    10751759    }
    10761760
     1761    /**
     1762     * Set up the next post and iterate index.
     1763     *
     1764     * @return object The next post to iterate over.
     1765     */
    10771766    function next_post() {
    10781767        $this->current_post++;
    … …  
    10821771    }
    10831772
     1773    /**
     1774     * Rewind the posts and reset post index.
     1775     */
    10841776    function rewind_posts() {
    10851777        $this->current_post = -1;
    … …  
    10891781    }
    10901782
     1783    /**
     1784     * Whether there are posts left in the loop to iterate over.
     1785     *
     1786     * This method is used by {@link bp_forum_topic_posts()} as part of
     1787     * the while loop that controls iteration inside the blogs loop, eg:
     1788     *     while ( bp_forum_topic_posts() ) { ...
     1789     *
     1790     * @see bp_forum_topic_posts()
     1791     *
     1792     * @return bool True if there are more posts to show, otherwise false.
     1793     */
    10911794    function user_posts() {
    10921795        if ( $this->current_post + 1 < $this->post_count ) {
    … …  
    11021805    }
    11031806
     1807    /**
     1808     * Set up the current topic in the loop.
     1809     *
     1810     * @see bp_the_forum_topic_post()
     1811     */
    11041812    function the_post() {
    11051813        global $post;
    … …  
    11141822}
    11151823
     1824/**
     1825 * Initiate the loop for a single topic's posts.
     1826 *
     1827 * @param array $args {
     1828 *     Arguments for limiting the contents of the topic posts loop.
     1829 *     @type int $topic_id ID of the topic to which the posts belong.
     1830 *     @type int $per_page Number of items to return per page. Default: 15.
     1831 *     @type int $max Max items to return. Default: false.
     1832 *     @type string $order 'ASC' or 'DESC'.
     1833 * }
     1834 * @return bool True when posts are found corresponding to the args,
     1835 *         otherwise false.
     1836 */
    11161837function bp_has_forum_topic_posts( $args = '' ) {
    11171838    global $topic_template;
    … …  
    11461867}
    11471868
     1869/**
     1870 * Determine whether there are posts left in the loop.
     1871 *
     1872 * @return bool True when posts are found.
     1873 */
    11481874function bp_forum_topic_posts() {
    11491875    global $topic_template;
    … …  
    11511877}
    11521878
     1879/**
     1880 * Set up the current post in the loop.
     1881 *
     1882 * @return object
     1883 */
    11531884function bp_the_forum_topic_post() {
    11541885    global $topic_template;
    … …  
    11561887}
    11571888
     1889/**
     1890 * Output the ID of the current post in the loop.
     1891 */
    11581892function bp_the_topic_post_id() {
    11591893    echo bp_get_the_topic_post_id();
    11601894}
     1895    /**
     1896     * Return the ID of the current post in the loop.
     1897     *
     1898     * @return int ID of the current post in the loop.
     1899     */
    11611900    function bp_get_the_topic_post_id() {
    11621901        global $topic_template;
    … …  
    11651904    }
    11661905
     1906/**
     1907 * Output the content of the current post in the loop.
     1908 */
    11671909function bp_the_topic_post_content() {
    11681910    echo bp_get_the_topic_post_content();
    11691911}
     1912    /**
     1913     * Return the content of the current post in the loop.
     1914     *
     1915     * @return string Content of the current post.
     1916     */
    11701917    function bp_get_the_topic_post_content() {
    11711918        global $topic_template;
    … …  
    11741921    }
    11751922
     1923/**
     1924 * Output the CSS class of the current post in the loop.
     1925 */
    11761926function bp_the_topic_post_css_class() {
    11771927    echo bp_get_the_topic_post_css_class();
    11781928}
    1179 
     1929    /**
     1930     * Return the CSS class of the current post in the loop.
     1931     *
     1932     * May contain strings 'alt', 'deleted', or 'open', depending on
     1933     * context.
     1934     *
     1935     * @return string String to put in the 'class' attribute of the current
     1936     *         post.
     1937     */
    11801938    function bp_get_the_topic_post_css_class() {
    11811939        global $topic_template;
    … …  
    11951953    }
    11961954
     1955/**
     1956 * Output the avatar of the user who posted the current post in the loop.
     1957 *
     1958 * @see bp_get_the_topic_post_poster_avatar() for a description of arguments.
     1959 *
     1960 * @param array $args See {@link bp_get_the_topic_post_poster_avatar()}.
     1961 */
    11971962function bp_the_topic_post_poster_avatar( $args = '' ) {
    11981963    echo bp_get_the_topic_post_poster_avatar( $args );
    11991964}
     1965    /**
     1966     * Return the avatar of the user who posted the current post in the loop.
     1967     *
     1968     * @param array $args {
     1969     *     Arguments for building the avatar.
     1970     *     @type string $type Avatar type. 'thumb' or 'full'. Default:
     1971     *           'thumb'.
     1972     *     @type int $width Width of the avatar, in pixels. Default: the
     1973     *           width corresponding to $type.
     1974     *           See {@link bp_core_fetch_avatar()}.
     1975     *     @type int $height Height of the avatar, in pixels. Default: the
     1976     *           height corresponding to $type.
     1977     *           See {@link bp_core_fetch_avatar()}.
     1978     *     @type string $alt The text of the image's 'alt' attribute.
     1979     *           Default: 'Profile picture of [user name]'.
     1980     * }
     1981     * @return string HTML of user avatar.
     1982     */
    12001983    function bp_get_the_topic_post_poster_avatar( $args = '' ) {
    12011984        global $topic_template;
    … …  
    12141997    }
    12151998
     1999/**
     2000 * Output the name of the user who posted the current post in the loop.
     2001 */
    12162002function bp_the_topic_post_poster_name() {
    12172003    echo bp_get_the_topic_post_poster_name();
    12182004}
     2005    /**
     2006     * Return the name of the user who posted the current post in the loop.
     2007     *
     2008     * @return string Name of the user who posted the current post.
     2009     */
    12192010    function bp_get_the_topic_post_poster_name() {
    12202011        global $topic_template;
    … …  
    12262017    }
    12272018
     2019/**
     2020 * Output a link to the profile of the user who posted the current post.
     2021 */
    12282022function bp_the_topic_post_poster_link() {
    12292023    echo bp_get_the_topic_post_poster_link();
    12302024}
     2025    /**
     2026     * Return a link to the profile of the user who posted the current post.
     2027     *
     2028     * @return string Link to the profile of the user who posted the
     2029     *         current post.
     2030     */
    12312031    function bp_get_the_topic_post_poster_link() {
    12322032        global $topic_template;
    … …  
    12352035    }
    12362036
     2037/**
     2038 * Output a 'since' string describing when the current post in the loop was posted.
     2039 */
    12372040function bp_the_topic_post_time_since() {
    12382041    echo bp_get_the_topic_post_time_since();
    12392042}
     2043    /**
     2044     * Return a 'since' string describing when the current post in the loop was posted.
     2045     *
     2046     * @see bp_core_time_since() for a description of return value.
     2047     *
     2048     * @return string
     2049     */
    12402050    function bp_get_the_topic_post_time_since() {
    12412051        global $topic_template;
    … …  
    12442054    }
    12452055
     2056/**
     2057 * Output whether the current post in the loop belongs to the logged-in user.
     2058 */
    12462059function bp_the_topic_post_is_mine() {
    12472060    echo bp_the_topic_post_is_mine();
    12482061}
     2062    /**
     2063     * Does the current post belong to the logged-in user?
     2064     *
     2065     * @return bool True if the current post in the loop was created by
     2066     *         the logged-in user, otherwise false.
     2067     */
    12492068    function bp_get_the_topic_post_is_mine() {
    12502069        global $bp, $topic_template;
    … …  
    12532072    }
    12542073
     2074/**
     2075 * Output the admin links for the current post in the loop.
     2076 *
     2077 * @see bp_get_the_post_admin_links() for a description of arguments.
     2078 *
     2079 * @param array $args See {@link bp_get_the_post_admin_links()}.
     2080 */
    12552081function bp_the_topic_post_admin_links( $args = '' ) {
    12562082    echo bp_get_the_topic_post_admin_links( $args );
    12572083}
     2084    /**
     2085     * Return the admin links for the current post in the loop.
     2086     *
     2087     * @param array $args {
     2088     *     @type string $separator The character to use when separating
     2089     *           links. Default: '|'.
     2090     * }
     2091     * @return HTML string containing the admin links for the current post.
     2092     */
    12582093    function bp_get_the_topic_post_admin_links( $args = '' ) {
    12592094        global $topic_template;
    … …  
    12812116    }
    12822117
     2118/**
     2119 * Output the text to edit when editing a post.
     2120 */
    12832121function bp_the_topic_post_edit_text() {
    12842122    echo bp_get_the_topic_post_edit_text();
    12852123}
     2124    /**
     2125     * Return the text to edit when editing a post.
     2126     *
     2127     * @return string Editable text.
     2128     */
    12862129    function bp_get_the_topic_post_edit_text() {
    12872130        $post = bp_forums_get_post( bp_action_variable( 4 ) );
    … …  
    12892132    }
    12902133
     2134/**
     2135 * Output the pagination links for the current topic.
     2136 */
    12912137function bp_the_topic_pagination() {
    12922138    echo bp_get_the_topic_pagination();
    12932139}
     2140    /**
     2141     * Return the pagination links for the current topic page.
     2142     *
     2143     * @return string HTML pagination links.
     2144     */
    12942145    function bp_get_the_topic_pagination() {
    12952146        global $topic_template;
    … …  
    12982149    }
    12992150
     2151/**
     2152 * Return the pagination count for the current topic page.
     2153 *
     2154 * The "count" is a string of the form "Viewing x of y posts".
     2155 *
     2156 * @return string
     2157 */
    13002158function bp_the_topic_pagination_count() {
    13012159    global $bp, $topic_template;
    … …  
    13092167}
    13102168
     2169/**
     2170 * Output whether this is the last page in the current topic.
     2171 */
    13112172function bp_the_topic_is_last_page() {
    13122173    echo bp_get_the_topic_is_last_page();
    13132174}
     2175    /**
     2176     * Is this the last page in the current topic?
     2177     *
     2178     * @return bool True if this is the last page of posts for the current
     2179     *         topic, otherwise false.
     2180     */
    13142181    function bp_get_the_topic_is_last_page() {
    13152182        global $topic_template;
    … …  
    13192186
    13202187/**
    1321  * Echoes the forums directory search form
     2188 * Output the forums directory search form.
    13222189 */
    13232190function bp_directory_forums_search_form() {
    … …  
    13332200}
    13342201
     2202/**
     2203 * Output the link to a given forum.
     2204 *
     2205 * @see bp_get_forum_permalink() for a description of arguments.
     2206 *
     2207 * @param int $forum_id See {@link bp_get_forum_permalink()}.
     2208 */
    13352209function bp_forum_permalink( $forum_id = 0 ) {
    13362210    echo bp_get_forum_permalink( $forum_id );
    13372211}
     2212    /**
     2213     * Return the permalink to a given forum.
     2214     *
     2215     * @param int $forum_id Optional. Defaults to the current forum, if
     2216     *        there is one.
     2217     * @return string|bool False on failure, a URL on success.
     2218     */
    13382219    function bp_get_forum_permalink( $forum_id = 0 ) {
    13392220        global $bp;
    … …  
    13572238    }
    13582239
     2240/**
     2241 * Output the name of a given forum.
     2242 *
     2243 * @see bp_get_forum_name() for a description of parameters.
     2244 *
     2245 * @param int $forum_id See {@link bp_get_forum_name()}.
     2246 */
    13592247function bp_forum_name( $forum_id = 0 ) {
    13602248    echo bp_get_forum_name( $forum_id );
    13612249}
     2250    /**
     2251     * Return the name of a given forum.
     2252     *
     2253     * @param int $forum_id Optional. Defaults to the current forum, if
     2254     *        there is one.
     2255     * @return string|bool False on failure, a name on success.
     2256     */
    13622257    function bp_get_forum_name( $forum_id = 0 ) {
    13632258        global $bp;
    … …  
    13752270    }
    13762271
     2272/**
     2273 * Get a heatmap of forum tags for the installation.
     2274 *
     2275 * A wrapper for {@link bb_tag_heat_map}, which provides it with BP-friendly
     2276 * defaults.
     2277 *
     2278 * @param array $args {
     2279 *     An array of optional arguments.
     2280 *     @type int $smallest Size of the smallest link. Default: 10.
     2281 *     @type int $largest Size of the largest link. Default: 42.
     2282 *     @type string $sizing Unit for $largest and $smallest. Default: 'px'.
     2283 *     @type int $limit Max number of tags to display. Default: 50.
     2284 * }
     2285 */
    13772286function bp_forums_tag_heat_map( $args = '' ) {
    13782287    $defaults = array(
    … …  
    13902299
    13912300/**
    1392  * Echo the current topic's tag list, comma-separated
    1393  *
    1394  * @package BuddyPress
    1395  * @since BuddyPress (1.5)
     2301 * Output the current topic's tag list, comma-separated
     2302 *
     2303 * @since BuddyPress (1.5.0)
    13962304 */
    13972305function bp_forum_topic_tag_list() {
    … …  
    13992307}
    14002308    /**
    1401      * Get the current topic's tag list
    1402      *
    1403      * @package BuddyPress
    1404      * @since BuddyPress (1.5)
    1405      *
    1406      * @param string $format 'string' returns comma-separated string; otherwise returns array
     2309     * Get the current topic's tag list.
     2310     *
     2311     * @since BuddyPress (1.5.0)
     2312     *
     2313     * @param string $format 'string' returns comma-separated string;
     2314     *        otherwise returns array.
    14072315     * @return mixed $tags
    14082316     */
    … …  
    14272335
    14282336/**
    1429  * Returns true if the current topic has tags
    1430  *
    1431  * @package BuddyPress
    1432  * @since BuddyPress (1.5)
    1433  *
    1434  * @return bool
     2337 * Does the current topic have any tags?
     2338 *
     2339 * @since BuddyPress (1.5.0)
     2340 *
     2341 * @return bool True if the current topic has tags, otherwise false.
    14352342 */
    14362343function bp_forum_topic_has_tags() {
    … …  
    14452352}
    14462353
     2354/**
     2355 * Output a URL to use in as a forum form 'action'.
     2356 */
    14472357function bp_forum_action() {
    14482358    echo bp_get_forum_action();
    14492359}
     2360    /**
     2361     * Get a URL to use in as a forum form 'action'.
     2362     *
     2363     * @return string URL of the current page, minus query args.
     2364     */
    14502365    function bp_get_forum_action() {
    14512366        global $topic_template;
    … …  
    14542369    }
    14552370
     2371/**
     2372 * Output a URL to use in as a forum topic form 'action'.
     2373 */
    14562374function bp_forum_topic_action() {
    14572375    echo bp_get_forum_topic_action();
    14582376}
     2377    /**
     2378     * Get a URL to use in as a forum topic form 'action'.
     2379     *
     2380     * @return string URL of the current page, minus query args.
     2381     */
    14592382    function bp_get_forum_topic_action() {
    14602383        return apply_filters( 'bp_get_forum_topic_action', $_SERVER['REQUEST_URI'] );
    14612384    }
    14622385
     2386/**
     2387 * Output the total topic count for a given user.
     2388 *
     2389 * @see bp_get_forum_topic_count_for_user() for description of parameters.
     2390 *
     2391 * @param int $user_id See {@link bp_get_forum_topic_count_for_user()}.
     2392 */
    14632393function bp_forum_topic_count_for_user( $user_id = 0 ) {
    14642394    echo bp_get_forum_topic_count_for_user( $user_id );
    14652395}
     2396    /**
     2397     * Return the total topic count for a given user.
     2398     *
     2399     * @param int $user_id See {@link bp_forums_total_topic_count_for_user}.
     2400     */
    14662401    function bp_get_forum_topic_count_for_user( $user_id = 0 ) {
    14672402        return apply_filters( 'bp_get_forum_topic_count_for_user', bp_forums_total_topic_count_for_user( $user_id ) );
    14682403    }
    14692404
     2405/**
     2406 * Output the total topic count for a given user.
     2407 *
     2408 * @see bp_get_forum_topic_count() for description of parameters.
     2409 *
     2410 * @param int $user_id See {@link bp_get_forum_topic_count()}.
     2411 */
    14702412function bp_forum_topic_count( $user_id = 0 ) {
    14712413    echo bp_get_forum_topic_count( $user_id );
    14722414}
     2415    /**
     2416     * Return the total topic count for a given user.
     2417     *
     2418     * @param int $user_id See {@link bp_forums_total_topic_count()}.
     2419     */
    14732420    function bp_get_forum_topic_count( $user_id = 0 ) {
    14742421        return apply_filters( 'bp_get_forum_topic_count', bp_forums_total_topic_count( $user_id ) );
Note: See TracChangeset for help on using the changeset viewer.