Skip to:
Content

BuddyPress.org


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

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

File:
1 edited

Legend:

Unmodified
Added
Removed

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