Skip to:
Content

BuddyPress.org

Changeset 8481


Ignore:
Timestamp:
06/07/2014 11:47:51 PM (5 years ago)
Author:
boonebgorges
Message:

Improve inline documentation in bp-messages.

See #5022

Location:
trunk/src/bp-messages
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/bp-messages/bp-messages-functions.php

    r8185 r8481  
    1616if ( !defined( 'ABSPATH' ) ) exit;
    1717
     18/**
     19 * Create a new message.
     20 *
     21 * @param array $args {
     22 *     Array of arguments.
     23 *     @type int $sender_id Optional. ID of the user who is sending the
     24 *           message. Default: ID of the logged-in user.
     25 *     @type int $thread_id Optional. ID of the parent thread. Leave blank to
     26 *           create a new thread for the message.
     27 *     @type array $recipients IDs or usernames of message recipients. If this
     28 *           is an existing thread, it is unnecessary to pass a $recipients
     29 *           argument - existing thread recipients will be assumed.
     30 *     @type string $subject Optional. Subject line for the message. For
     31 *           existing threads, the existing subject will be used. For new
     32 *           threads, 'No Subject' will be used if no $subject is provided.
     33 *     @type string $content Content of the message. Cannot be empty.
     34 *     @type string $date_sent Date sent, in 'Y-m-d H:i:s' format. Default:
     35 *           current date/time.
     36 * }
     37 * @return int|bool ID of the message thread on success, false on failure.
     38 */
    1839function messages_new_message( $args = '' ) {
    1940
     
    123144}
    124145
    125 
     146/**
     147 * Send a notice.
     148 *
     149 * @param string $subject Subject of the notice.
     150 * @param string $message Content of the notice.
     151 * @return bool True on success, false on failure.
     152 */
    126153function messages_send_notice( $subject, $message ) {
    127154    if ( !bp_current_user_can( 'bp_moderate' ) || empty( $subject ) || empty( $message ) ) {
     
    143170}
    144171
     172/**
     173 * Delete message thread(s).
     174 *
     175 * @param int|array Thread ID or array of thread IDs.
     176 * @return bool True on success, false on failure.
     177 */
    145178function messages_delete_thread( $thread_ids ) {
    146179    do_action( 'messages_before_delete_thread', $thread_ids );
     
    170203}
    171204
     205/**
     206 * Check whether a user has access to a thread.
     207 *
     208 * @param int $thread_id ID of the thread.
     209 * @param int $user_id Optional. ID of the user. Default: ID of the logged-in
     210 *        user.
     211 * @return int|null Message ID if the user has access, otherwise null.
     212 */
    172213function messages_check_thread_access( $thread_id, $user_id = 0 ) {
    173214    if ( empty( $user_id ) )
     
    177218}
    178219
     220/**
     221 * Mark a thread as read.
     222 *
     223 * Wrapper for {@link BP_Messages_Thread::mark_as_read()}.
     224 *
     225 * @param int $thread_id ID of the thread.
     226 */
    179227function messages_mark_thread_read( $thread_id ) {
    180228    return BP_Messages_Thread::mark_as_read( $thread_id );
    181229}
    182230
     231/**
     232 * Mark a thread as unread.
     233 *
     234 * Wrapper for {@link BP_Messages_Thread::mark_as_unread()}.
     235 *
     236 * @param int $thread_id ID of the thread.
     237 */
    183238function messages_mark_thread_unread( $thread_id ) {
    184239    return BP_Messages_Thread::mark_as_unread( $thread_id );
    185240}
    186241
     242/**
     243 * Set messages-related cookies.
     244 *
     245 * Saves the 'bp_messages_send_to', 'bp_messages_subject', and
     246 * 'bp_messages_content' cookies, which are used when setting up the default
     247 * values on the messages page.
     248 *
     249 * @param string $recipients Comma-separated list of recipient usernames.
     250 * @param string $subject Subject of the message.
     251 * @param string $content Content of the message.
     252 */
    187253function messages_add_callback_values( $recipients, $subject, $content ) {
    188254    @setcookie( 'bp_messages_send_to', $recipients, time() + 60 * 60 * 24, COOKIEPATH );
     
    191257}
    192258
     259/**
     260 * Unset messages-related cookies.
     261 *
     262 * @see messages_add_callback_values()
     263 */
    193264function messages_remove_callback_values() {
    194265    @setcookie( 'bp_messages_send_to', false, time() - 1000, COOKIEPATH );
     
    197268}
    198269
     270/**
     271 * Get the unread messages count for a user.
     272 *
     273 * @param int $user_id Optional. ID of the user. Default: ID of the
     274 *        logged-in user.
     275 * @return int
     276 */
    199277function messages_get_unread_count( $user_id = 0 ) {
    200278    if ( empty( $user_id ) )
     
    204282}
    205283
     284/**
     285 * Check whether a user is the sender of a message.
     286 *
     287 * @param int $user_id ID of the user.
     288 * @param int $message_id ID of the message.
     289 * @return int|null Returns the ID of the message if the user is the
     290 *         sender, otherwise null.
     291 */
    206292function messages_is_user_sender( $user_id, $message_id ) {
    207293    return BP_Messages_Message::is_user_sender( $user_id, $message_id );
    208294}
    209295
     296/**
     297 * Get the ID of the sender of a message.
     298 *
     299 * @param int $message_id ID of the message.
     300 * @return int|null The ID of the sender if found, otherwise null.
     301 */
    210302function messages_get_message_sender( $message_id ) {
    211303    return BP_Messages_Message::get_message_sender( $message_id );
    212304}
    213305
     306/**
     307 * Check whether a message thread exists.
     308 *
     309 * @param int $thread_id ID of the thread.
     310 * @return int|null The message thread ID on success, null on failure.
     311 */
    214312function messages_is_valid_thread( $thread_id ) {
    215313    return BP_Messages_Thread::is_valid( $thread_id );
  • trunk/src/bp-messages/bp-messages-loader.php

    r8223 r8481  
    1313if ( !defined( 'ABSPATH' ) ) exit;
    1414
     15/**
     16 * Implementation of BP_Component for the Messages component.
     17 *
     18 * @since BuddyPress (1.5.0)
     19 */
    1520class BP_Messages_Component extends BP_Component {
    1621    /**
     
    2429
    2530    /**
    26      * Start the messages component creation process
    27      *
    28      * @since BuddyPress (1.5)
     31     * Start the messages component creation process.
     32     *
     33     * @since BuddyPress (1.5.0)
    2934     */
    3035    public function __construct() {
     
    4045
    4146    /**
    42      * Include files
     47     * Include files.
     48     *
     49     * @since BuddyPress (1.5.0)
     50     *
     51     * @param array $includes See {BP_Component::includes()} for details.
    4352     */
    4453    public function includes( $includes = array() ) {
     
    6271
    6372    /**
    64      * Setup globals
     73     * Set up globals for the Messages component.
    6574     *
    6675     * The BP_MESSAGES_SLUG constant is deprecated, and only used here for
    6776     * backwards compatibility.
    6877     *
    69      * @since BuddyPress (1.5)
     78     * @since BuddyPress (1.5.0)
     79     *
     80     * @param array $args Not used.
    7081     */
    7182    public function setup_globals( $args = array() ) {
     
    99110
    100111    /**
    101      * Setup BuddyBar navigation
     112     * Set up navigation for user pages.
     113     *
     114     * @param array $main_nav See {BP_Component::setup_nav()} for details.
     115     * @param array $sub_nav See {BP_Component::setup_nav()} for details.
    102116     */
    103117    public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
     
    182196
    183197    /**
    184      * Set up the Toolbar
     198     * Set up the Toolbar.
     199     *
     200     * @param array $wp_admin_nav See {BP_Component::setup_admin_bar()}
     201     *        for details.
    185202     */
    186203    public function setup_admin_bar( $wp_admin_nav = array() ) {
     
    251268
    252269    /**
    253      * Sets up the title for pages and <title>
     270     * Set up the title for pages and <title>.
    254271     */
    255272    public function setup_title() {
     
    273290}
    274291
     292/**
     293 * Bootstrap the Messages component.
     294 */
    275295function bp_setup_messages() {
    276296    buddypress()->messages = new BP_Messages_Component();
Note: See TracChangeset for help on using the changeset viewer.