Changeset 9862 for trunk/src/bp-messages/bp-messages-functions.php

Timestamp:

05/12/2015 04:39:07 AM (10 years ago)

Author:

tw2113

Message:

First pass at messages component docs cleanup.

See #6403.

File:

• trunk/src/bp-messages/bp-messages-functions.php (modified) (14 diffs)

trunk/src/bp-messages/bp-messages-functions.php

@@ -2 +2 @@
 
 /**
- * BuddyPress Messages Functions
+ * BuddyPress Messages Functions.
  *
  * Business functions are where all the magic happens in BuddyPress. They will
@@ -19 +19 @@
  * Create a new message.
  *
- * @param array $args {
+ * @param array|string $args {
  *     Array of arguments.
- *     @type int $sender_id Optional. ID of the user who is sending the
- *           message. Default: ID of the logged-in user.
- *     @type int $thread_id Optional. ID of the parent thread. Leave blank to
- *           create a new thread for the message.
- *     @type array $recipients IDs or usernames of message recipients. If this
- *           is an existing thread, it is unnecessary to pass a $recipients
- *           argument - existing thread recipients will be assumed.
- *     @type string $subject Optional. Subject line for the message. For
- *           existing threads, the existing subject will be used. For new
- *           threads, 'No Subject' will be used if no $subject is provided.
- *     @type string $content Content of the message. Cannot be empty.
- *     @type string $date_sent Date sent, in 'Y-m-d H:i:s' format. Default:
- *           current date/time.
+ *     @type int    $sender_id  Optional. ID of the user who is sending the
+ *                              message. Default: ID of the logged-in user.
+ *     @type int    $thread_id  Optional. ID of the parent thread. Leave blank to
+ *                              create a new thread for the message.
+ *     @type array  $recipients IDs or usernames of message recipients. If this
+ *                              is an existing thread, it is unnecessary to pass a $recipients
+ *                              argument - existing thread recipients will be assumed.
+ *     @type string $subject    Optional. Subject line for the message. For
+ *                              existing threads, the existing subject will be used. For new
+ *                              threads, 'No Subject' will be used if no $subject is provided.
+ *     @type string $content    Content of the message. Cannot be empty.
+ *     @type string $date_sent  Date sent, in 'Y-m-d H:i:s' format. Default: current date/time.
  * }
  * @return int|bool ID of the message thread on success, false on failure.
@@ -174 +173 @@
  * @param string $subject Subject of the notice.
  * @param string $message Content of the notice.
+ *
  * @return bool True on success, false on failure.
  */
@@ -207 +207 @@
  *
  * @param int|array Thread ID or array of thread IDs.
+ *
  * @return bool True on success, false on failure.
  */
@@ -258 +259 @@
  *
  * @param int $thread_id ID of the thread.
- * @param int $user_id Optional. ID of the user. Default: ID of the logged-in
- *        user.
+ * @param int $user_id   Optional. ID of the user. Default: ID of the logged-in user.
+ *
  * @return int|null Message ID if the user has access, otherwise null.
  */
@@ -300 +301 @@
  *
  * @param string $recipients Comma-separated list of recipient usernames.
- * @param string $subject Subject of the message.
- * @param string $content Content of the message.
+ * @param string $subject    Subject of the message.
+ * @param string $content    Content of the message.
  */
 function messages_add_callback_values( $recipients, $subject, $content ) {
@@ -323 +324 @@
  * Get the unread messages count for a user.
  *
- * @param int $user_id Optional. ID of the user. Default: ID of the
- *        logged-in user.
+ * @param int $user_id Optional. ID of the user. Default: ID of the logged-in user.
+ *
  * @return int
  */
@@ -338 +339 @@
  * Check whether a user is the sender of a message.
  *
- * @param int $user_id ID of the user.
+ * @param int $user_id    ID of the user.
  * @param int $message_id ID of the message.
+ *
  * @return int|null Returns the ID of the message if the user is the
- *         sender, otherwise null.
+ *                  sender, otherwise null.
  */
 function messages_is_user_sender( $user_id, $message_id ) {
@@ -351 +353 @@
  *
  * @param int $message_id ID of the message.
+ *
  * @return int|null The ID of the sender if found, otherwise null.
  */
@@ -361 +364 @@
  *
  * @param int $thread_id ID of the thread.
+ *
  * @return int|null The message thread ID on success, null on failure.
  */
@@ -393 +397 @@
  *
  * @see delete_metadata() for full documentation excluding $meta_type variable.
+ *
+ * @param int         $message_id ID of the message to have meta deleted for.
+ * @param string|bool $meta_key   Meta key to delete. Default false.
+ * @param string|bool $meta_value Meta value to delete. Default false.
+ * @param bool        $delete_all Whether or not to delete all meta data.
+ *
+ * @return bool
  */
 function bp_messages_delete_meta( $message_id, $meta_key = false, $meta_value = false, $delete_all = false ) {
@@ -429 +440 @@
  *
  * @see get_metadata() for full documentation excluding $meta_type variable.
+ *
+ * @param int    $message_id ID of the message to retrieve meta for.
+ * @param string $meta_key   Meta key to retrieve. Default empty string.
+ * @param bool   $single     Whether or not to fetch all or a single value.
+ *
+ * @return mixed
  */
 function bp_messages_get_meta( $message_id, $meta_key = '', $single = true ) {
@@ -444 +461 @@
  *
  * @see update_metadata() for full documentation excluding $meta_type variable.
+ *
+ * @param int         $message_id ID of the message to have meta deleted for.
+ * @param string|bool $meta_key   Meta key to update.
+ * @param string|bool $meta_value Meta value to update.
+ * @param string      $prev_value If specified, only update existing metadata entries with
+ *                                the specified value. Otherwise, update all entries.
+ *
+ * @return mixed
  */
 function bp_messages_update_meta( $message_id, $meta_key, $meta_value, $prev_value = '' ) {
@@ -459 +484 @@
  *
  * @see add_metadata() for full documentation excluding $meta_type variable.
+ *
+ * @param int         $message_id ID of the message to have meta deleted for.
+ * @param string|bool $meta_key   Meta key to update.
+ * @param string|bool $meta_value Meta value to update.
+ * @param bool        $unique     Whether the specified metadata key should be
+ *                                unique for the object. If true, and the object
+ *                                already has a value for the specified metadata key,
+ *                                no change will be made.
+ * @return mixed
  */
 function bp_messages_add_meta( $message_id, $meta_key, $meta_value, $unique = false ) {