Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
10/08/2013 08:58:00 PM (11 years ago)
Author:
boonebgorges
Message:

Inline docs improvements in bp-activity-functions.php and -classes.php

See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-activity/bp-activity-functions.php

    r7349 r7398  
    22
    33/**
    4  * BuddyPress Activity Functions
    5  *
    6  * Functions for the Activity Streams component
     4 * BuddyPress Activity Functions.
     5 *
     6 * Functions for the Activity Streams component.
    77 *
    88 * @package BuddyPress
    … …  
    1414
    1515/**
    16  * Checks $bp pages global and looks for directory page
     16 * Check whether the $bp global lists an activity directory page.
    1717 *
    1818 * @since BuddyPress (1.5)
    … …  
    2020 * @global object $bp BuddyPress global settings
    2121 *
    22  * @return bool True if set, False if empty
     22 * @return bool True if activity directory page is found, otherwise false.
    2323 */
    2424function bp_activity_has_directory() {
    … …  
    4646 *
    4747 * @uses apply_filters() To call 'bp_activity_do_mentions' hook.
     48 *
    4849 * @return bool $retval True to enable mentions, false to disable.
    4950 */
    … …  
    5354
    5455/**
    55  * Searches through the content of an activity item to locate usernames,
    56  * designated by an @ sign.
     56 * Locate usernames in an activity content string, as designated by an @ sign.
    5757 *
    5858 * @since BuddyPress (1.5)
    5959 *
    6060 * @param string $content The content of the activity, usually found in $activity->content.
    61  * @return mixed Associative array with user ID as key and username as value. Boolean false if no mentions found.
     61 * @return array|bool Associative array with user ID as key and username as value. Boolean false if no mentions found.
    6262 */
    6363function bp_activity_find_mentions( $content ) {
    … …  
    9292
    9393/**
    94  * Resets a user's unread mentions list and count
     94 * Reset a user's unread mentions list and count.
    9595 *
    9696 * @since BuddyPress (1.5)
    9797 *
    98  * @param int $user_id The id of the user whose unread mentions are being reset
    9998 * @uses bp_delete_user_meta()
     99 *
     100 * @param int $user_id The id of the user whose unread mentions are being reset.
    100101 */
    101102function bp_activity_clear_new_mentions( $user_id ) {
    … …  
    114115 * @since BuddyPress (1.5)
    115116 *
    116  * @param int $activity_id The unique id for the activity item
    117  * @param string $action Can be 'delete' or 'add'. Defaults to 'add'.
    118  *
    119117 * @uses bp_activity_find_mentions()
    120118 * @uses bp_activity_update_mention_count_for_user()
     119 *
     120 * @param int $activity_id The unique id for the activity item.
     121 * @param string $action Can be 'delete' or 'add'. Defaults to 'add'.
    121122 */
    122123function bp_activity_adjust_mention_count( $activity_id = 0, $action = 'add' ) {
    … …  
    141142
    142143/**
    143  * Updates the mention count for the user in question.
     144 * Update the mention count for a given user.
    144145 *
    145146 * This function should be used when you've already parsed your activity item
    … …  
    148149 * @since BuddyPress (1.7)
    149150 *
    150  * @param int $user_id The user ID
    151  * @param int $activity_id The unique id for the activity item
    152  * @param string $action Can be 'delete' or 'add'. Defaults to 'add'
    153  *
    154151 * @uses bp_get_user_meta()
    155152 * @uses bp_update_user_meta()
     153 *
     154 * @param int $user_id The user ID.
     155 * @param int $activity_id The unique ID for the activity item.
     156 * @param string $action 'delete' or 'add'. Default: 'add'.
    156157 * @return bool
    157158 */
    … …  
    195196
    196197/**
    197  * Formats notifications related to activity
     198 * Format notifications related to activity.
    198199 *
    199200 * @since BuddyPress (1.5)
    200  *
    201  * @param string $action The type of activity item. Just 'new_at_mention' for now
    202  * @param int $item_id The activity id
    203  * @param int $secondary_item_id In the case of at-mentions, this is the mentioner's id
    204  * @param int $total_items The total number of notifications to format
    205  * @param string $format 'string' to get a BuddyBar-compatible notification, 'array' otherwise
    206201 *
    207202 * @uses bp_loggedin_user_domain()
    208203 * @uses bp_get_activity_slug()
    209204 * @uses bp_core_get_user_displayname()
    210  * @uses apply_filters() To call the 'bp_activity_multiple_at_mentions_notification' hook
    211  * @uses apply_filters() To call the 'bp_activity_single_at_mentions_notification' hook
    212  * @uses do_action() To call 'activity_format_notifications' hook
    213  *
    214  * @return string $return Formatted @mention notification
     205 * @uses apply_filters() To call the 'bp_activity_multiple_at_mentions_notification' hook.
     206 * @uses apply_filters() To call the 'bp_activity_single_at_mentions_notification' hook.
     207 * @uses do_action() To call 'activity_format_notifications' hook.
     208 *
     209 * @param string $action The type of activity item. Just 'new_at_mention' for now.
     210 * @param int $item_id The activity ID.
     211 * @param int $secondary_item_id In the case of at-mentions, this is the mentioner's ID.
     212 * @param int $total_items The total number of notifications to format.
     213 * @param string $format 'string' to get a BuddyBar-compatible notification, 'array' otherwise.
     214 * @return string $return Formatted @mention notification.
    215215 */
    216216function bp_activity_format_notifications( $action, $item_id, $secondary_item_id, $total_items, $format = 'string' ) {
    … …  
    251251
    252252/**
    253  * Sets the current action for a given activity stream location
     253 * Set the current action for a given activity stream location.
    254254 *
    255255 * @since BuddyPress (1.1)
    256  *
    257  * @param string $component_id
    258  * @param string $key
    259  * @param string $value
    260256 *
    261257 * @global object $bp BuddyPress global settings
    262258 * @uses apply_filters() To call the 'bp_activity_set_action' hook
    263259 *
    264  * @return bool False if any param is empty, otherwise true
     260 * @param string $component_id The unique string ID of the component.
     261 * @param string $key The action key.
     262 * @param string $value The action value.
     263 * @return bool False if any param is empty, otherwise true.
    265264 */
    266265function bp_activity_set_action( $component_id, $key, $value ) {
    … …  
    289288
    290289/**
    291  * Retreives the current action from a component and key
     290 * Retreive the current action from a component and key.
    292291 *
    293292 * @since BuddyPress (1.1)
    294293 *
    295  * @param string $component_id
    296  * @param string $key
    297  *
    298  * @global object $bp BuddyPress global settings
    299  * @uses apply_filters() To call the 'bp_activity_get_action' hook
    300  *
    301  * @return mixed False on error, action on success
     294 * @global object $bp BuddyPress global settings.
     295 * @uses apply_filters() To call the 'bp_activity_get_action' hook.
     296 *
     297 * @param string $component_id The unique string ID of the component.
     298 * @param string $key The action key.
     299 * @return string|bool Action value if found, otherwise false.
    302300 */
    303301function bp_activity_get_action( $component_id, $key ) {
    … …  
    312310
    313311/**
    314  * Fetch details of all registered activity types
     312 * Fetch details of all registered activity types.
     313 *
     314 * @since BuddyPress (1.7)
    315315 *
    316316 * @return array array( type => description ), ...
    317  * @since BuddyPress (1.7)
    318317 */
    319318function bp_activity_get_types() {
    … …  
    340339
    341340/**
    342  * Get a users favorite activity stream items
     341 * Get a users favorite activity stream items.
    343342 *
    344343 * @since BuddyPress (1.2)
    345344 *
    346  * @param int $user_id
    347  *
    348345 * @uses bp_get_user_meta()
    349  * @uses apply_filters() To call the 'bp_activity_get_user_favorites' hook
    350  *
    351  * @return array Array of users favorite activity stream ID's
     346 * @uses apply_filters() To call the 'bp_activity_get_user_favorites' hook.
     347 *
     348 * @param int $user_id ID of the user whose favorites are being queried.
     349 * @return array IDs of the user's favorite activity items.
    352350 */
    353351function bp_activity_get_user_favorites( $user_id = 0 ) {
    … …  
    364362
    365363/**
    366  * Add an activity stream item as a favorite for a user
     364 * Add an activity stream item as a favorite for a user.
    367365 *
    368366 * @since BuddyPress (1.2)
    369  *
    370  * @param int $activity_id
    371  * @param int $user_id
    372367 *
    373368 * @uses is_user_logged_in()
    … …  
    376371 * @uses bp_update_user_meta()
    377372 * @uses bp_activity_update_meta()
    378  * @uses do_action() To call the 'bp_activity_add_user_favorite' hook
    379  * @uses do_action() To call the 'bp_activity_add_user_favorite_fail' hook
    380  *
    381  * @return bool True on success, false on failure
     373 * @uses do_action() To call the 'bp_activity_add_user_favorite' hook.
     374 * @uses do_action() To call the 'bp_activity_add_user_favorite_fail' hook.
     375 *
     376 * @param int $activity_id ID of the activity item being favorited.
     377 * @param int $user_id ID of the user favoriting the activity item.
     378 * @return bool True on success, false on failure.
    382379 */
    383380function bp_activity_add_user_favorite( $activity_id, $user_id = 0 ) {
    … …  
    421418
    422419/**
    423  * Remove an activity stream item as a favorite for a user
     420 * Remove an activity stream item as a favorite for a user.
    424421 *
    425422 * @since BuddyPress (1.2)
    426  *
    427  * @param int $activity_id
    428  * @param int $user_id
    429423 *
    430424 * @uses is_user_logged_in()
    … …  
    433427 * @uses bp_activity_update_meta()
    434428 * @uses bp_update_user_meta()
    435  * @uses do_action() To call the 'bp_activity_remove_user_favorite' hook
    436  *
    437  * @return bool True on success, false on failure
     429 * @uses do_action() To call the 'bp_activity_remove_user_favorite' hook.
     430 *
     431 * @param int $activity_id ID of the activity item being unfavorited.
     432 * @param int $user_id ID of the user unfavoriting the activity item.
     433 * @return bool True on success, false on failure.
    438434 */
    439435function bp_activity_remove_user_favorite( $activity_id, $user_id = 0 ) {
    … …  
    485481
    486482/**
    487  * Check if activity exists by scanning content
     483 * Check whether an activity item exists with a given content string.
    488484 *
    489485 * @since BuddyPress (1.1)
    490486 *
    491  * @param string $content
    492  *
    493487 * @uses BP_Activity_Activity::check_exists_by_content() {@link BP_Activity_Activity}
    494  * @uses apply_filters() To call the 'bp_activity_check_exists_by_content' hook
    495  *
    496  * @return bool
     488 * @uses apply_filters() To call the 'bp_activity_check_exists_by_content' hook.
     489 *
     490 * @param string $content The content to filter by.
     491 * @return int|null The ID of the located activity item. Null if none is found.
    497492 */
    498493function bp_activity_check_exists_by_content( $content ) {
    … …  
    501496
    502497/**
    503  * Retrieve the last time activity was updated
     498 * Retrieve the last time activity was updated.
    504499 *
    505500 * @since BuddyPress (1.0)
    506501 *
    507502 * @uses BP_Activity_Activity::get_last_updated() {@link BP_Activity_Activity}
    508  * @uses apply_filters() To call the 'bp_activity_get_last_updated' hook
    509  *
    510  * @return string Date last updated
     503 * @uses apply_filters() To call the 'bp_activity_get_last_updated' hook.
     504 *
     505 * @return string Date last updated.
    511506 */
    512507function bp_activity_get_last_updated() {
    … …  
    515510
    516511/**
    517  * Retrieve the number of favorite activity stream items a user has
     512 * Retrieve the number of favorite activity stream items a user has.
    518513 *
    519514 * @since BuddyPress (1.2)
    520515 *
    521  * @param int $user_id
    522  *
    523516 * @uses BP_Activity_Activity::total_favorite_count() {@link BP_Activity_Activity}
    524517 *
    525  * @return int Total favorite count
     518 * @param int $user_id ID of the user whose favorite count is being requested.
     519 * @return int Total favorite count for the user.
    526520 */
    527521function bp_activity_total_favorites_for_user( $user_id = 0 ) {
    … …  
    537531
    538532/**
    539  * Delete a meta entry from the DB for an activity stream item
     533 * Delete a meta entry from the DB for an activity stream item.
    540534 *
    541535 * @since BuddyPress (1.2)
    542536 *
    543  * @param int $activity_id
    544  * @param string $meta_key
    545  * @param string $meta_value
    546  *
    547  * @global object $wpdb
    548  * @global object $bp BuddyPress global settings
     537 * @global object $wpdb WordPress database access object.
     538 * @global object $bp BuddyPress global settings.
    549539 * @uses wp_cache_delete()
    550540 * @uses is_wp_error()
    551541 *
    552  * @return bool True on success, false on failure
     542 * @param int $activity_id ID of the activity item whose metadata is being deleted.
     543 * @param string $meta_key Optional. The key of the metadata being deleted. If
     544 *                         omitted, all metadata associated with the activity
     545 *                         item will be deleted.
     546 * @param string $meta_value Optional. If present, the metadata will only be
     547 *                           deleted if the meta_value matches this parameter.
     548 * @return bool True on success, false on failure.
    553549 */
    554550function bp_activity_delete_meta( $activity_id, $meta_key = '', $meta_value = '' ) {
    … …  
    593589
    594590/**
    595  * Get activity meta
     591 * Get metadata for a given activity item.
    596592 *
    597593 * @since BuddyPress (1.2)
    598594 *
    599  * @param int $activity_id
    600  * @param string $meta_key
    601  *
    602  * @global object $wpdb
    603  * @global object $bp BuddyPress global settings
     595 * @global object $wpdb WordPress database access object.
     596 * @global object $bp BuddyPress global settings.
    604597 * @uses wp_cache_get()
    605598 * @uses wp_cache_set()
    606  * @uses apply_filters() To call the 'bp_activity_get_meta' hook
    607  *
    608  * @return bool
     599 * @uses apply_filters() To call the 'bp_activity_get_meta' hook.
     600 *
     601 * @param int $activity_id ID of the activity item whose metadata is being requseted.
     602 * @param string $meta_key Optional. If present, only the metadata matching
     603 *                         that meta key will be returned. Otherwise, all
     604 *                         metadata for the activity item will be fetched.
     605 * @return mixed The meta value(s) being requested.
    609606 */
    610607function bp_activity_get_meta( $activity_id = 0, $meta_key = '' ) {
    … …  
    658655
    659656/**
    660  * Update activity meta
     657 * Update a piece of activity meta.
    661658 *
    662659 * @since BuddyPress (1.2)
    663660 *
    664  * @param int $activity_id
    665  * @param string $meta_key
    666  * @param string $meta_value
    667  *
    668  * @global object $wpdb
    669  * @global object $bp BuddyPress global settings
     661 * @global object $wpdb WordPress database access object.
     662 * @global object $bp BuddyPress global settings.
    670663 * @uses maybe_serialize()
    671664 * @uses bp_activity_delete_meta()
    672665 * @uses wp_cache_set()
    673666 *
    674  * @return bool True on success, false on failure
     667 * @param int $activity_id ID of the activity item whose metadata is being updated.
     668 * @param string $meta_key Key of the metadata being updated.
     669 * @param mixed $meta_value Value to be set.
     670 * @return bool True on success, false on failure.
    675671 */
    676672function bp_activity_update_meta( $activity_id, $meta_key, $meta_value ) {
    … …  
    720716
    721717/**
    722  * Completely remove a user's activity data
     718 * Completely remove a user's activity data.
    723719 *
    724720 * @since BuddyPress (1.5)
    725  *
    726  * @param int $user_id
    727721 *
    728722 * @uses is_user_logged_in()
    729723 * @uses bp_activity_delete()
    730724 * @uses bp_delete_user_meta()
    731  * @uses do_action() To call the 'bp_activity_remove_data' hook
    732  * @uses do_action() To call the 'bp_activity_remove_all_user_data' hook
     725 * @uses do_action() To call the 'bp_activity_remove_data' hook.
     726 * @uses do_action() To call the 'bp_activity_remove_all_user_data' hook.
     727 *
     728 * @param int $user_id ID of the user whose activity is being deleted.
    733729 */
    734730function bp_activity_remove_all_user_data( $user_id = 0 ) {
    … …  
    755751
    756752/**
    757  * Mark all of the user's activity as spam
    758  *
    759  * @global object $wpdb
    760  * @global object $bp BuddyPress global settings
    761  * @param int $user_id
     753 * Mark all of the user's activity as spam.
     754 *
    762755 * @since BuddyPress (1.6)
     756 *
     757 * @global object $wpdb WordPress database access object.
     758 * @global object $bp BuddyPress global settings.
     759 *
     760 * @param int $user_id ID of the user whose activity is being spammed.
    763761 */
    764762function bp_activity_spam_all_user_data( $user_id = 0 ) {
    … …  
    806804
    807805/**
    808  * Mark all of the user's activity as ham (not spam)
    809  *
    810  * @global object $wpdb
    811  * @global object $bp BuddyPress global settings
    812  * @param int $user_id
     806 * Mark all of the user's activity as ham (not spam).
     807 *
    813808 * @since BuddyPress (1.6)
     809 *
     810 * @global object $wpdb WordPress database access object.
     811 * @global object $bp BuddyPress global settings.
     812 *
     813 * @param int $user_id ID of the user whose activity is being hammed.
    814814 */
    815815function bp_activity_ham_all_user_data( $user_id = 0 ) {
    … …  
    859859 * Register the activity stream actions for updates
    860860 *
    861  * @global object $bp BuddyPress global settings
    862861 * @since BuddyPress (1.6)
     862 *
     863 * @global object $bp BuddyPress global settings.
    863864 */
    864865function bp_activity_register_activity_actions() {
    … …  
    883884
    884885/**
    885  * Retrieve an activity or activities
     886 * Retrieve an activity or activities.
     887 *
     888 * bp_activity_get() shares all arguments with BP_Activity_Activity::get(). The
     889 * following is a list of bp_activity_get() parameters that have different
     890 * default values from BP_Activity_Activity::get() (value in parentheses is
     891 * the default for the bp_activity_get()).
     892 *   - 'per_page' (false)
    886893 *
    887894 * @since BuddyPress (1.2)
    888895 *
    889  * @param array $args
    890  *
     896 * @see BP_Activity_Activity::get() For more information on accepted arguments
     897 *      and the format of the returned value.
    891898 * @uses wp_parse_args()
    892899 * @uses wp_cache_get()
    893900 * @uses wp_cache_set()
    894901 * @uses BP_Activity_Activity::get() {@link BP_Activity_Activity}
    895  * @uses apply_filters_ref_array() To call the 'bp_activity_get' hook
    896  *
    897  * @return object $activity The activity/activities object
     902 * @uses apply_filters_ref_array() To call the 'bp_activity_get' hook.
     903 *
     904 * @param array $args See BP_Activity_Activity::get() for description.
     905 * @return array $activity See BP_Activity_Activity::get() for description.
    898906 */
    899907function bp_activity_get( $args = '' ) {
    … …  
    968976
    969977/**
    970  * Fetch specific activity items
     978 * Fetch specific activity items.
    971979 *
    972980 * @since BuddyPress (1.2)
    973981 *
    974  * @param array $args See docs for $defaults for details
    975  *
     982 * @see BP_Activity_Activity::get() For more information on accepted arguments
    976983 * @uses wp_parse_args()
    977984 * @uses apply_filters() To call the 'bp_activity_get_specific' hook
    978985 * @uses BP_Activity_Activity::get() {@link BP_Activity_Activity}
    979986 *
    980  * @return array The array returned by BP_Activity_Activity::get()
     987 * @param array $args {
     988 *     All arguments and defaults are shared with BP_Activity_Activity::get(),
     989 *     except for the following:
     990 *     @string|int|array Single activity ID, comma-separated list of IDs, or
     991 *                       array of IDs.
     992 * }
     993 * @return array $activity See BP_Activity_Activity::get() for description.
    981994 */
    982995function bp_activity_get_specific( $args = '' ) {
    … …  
    10081021
    10091022/**
    1010  * Add an activity item
     1023 * Add an activity item.
    10111024 *
    10121025 * @since BuddyPress (1.1)
    1013  *
    1014  * @param array $args See docs for $defaults for details
    10151026 *
    10161027 * @uses wp_parse_args()
    … …  
    10201031 * @uses do_action() To call the 'bp_activity_add' hook
    10211032 *
    1022  * @return int The activity id
     1033 * @param array $args {
     1034 *     An array of arguments.
     1035 *     @int|bool $id Pass an activity ID to update an existing item, or false
     1036 *                   to create a new item. Default: false.
     1037 *     @string $action Optional. The activity action/description, typically
     1038 *                     something like "Joe posted an update".
     1039 *     @string $content Optional. The content of the activity item.
     1040 *     @string $component The unique name of the component associated with the
     1041 *                        activity item - 'groups', 'profile', etc.
     1042 *     @string $type The specific activity type, used for directory filtering.
     1043 *                   'new_blog_post', 'activity_update', etc.
     1044 *     @string $primary_link Optional. The URL for this item, as used in RSS
     1045 *                           feeds. Defaults to the URL for this activity
     1046 *                           item's permalink page.
     1047 *     @int|bool $user_id Optional. The ID of the user associated with the
     1048 *                        activity item. May be set to false or 0 if the item
     1049 *                        is not related to any user. Default: the ID of the
     1050 *                        currently logged-in user.
     1051 *     @int $item_id Optional. The ID of the associated item.
     1052 *     @int $secondary_item_id Optional. The ID of a secondary associated item.
     1053 *     @string $date_recorded Optional. The GMT time, in Y-m-d h:i:s format,
     1054 *                            when the item was recorded. Defaults to the
     1055 *                            current time.
     1056 *     @bool $hide_sitewide Should the item be hidden on sitewide streams?
     1057 *                          Default: false.
     1058 *     @bool $is_spam Should the item be marked as spam? Default: false.
     1059 * }
     1060 * @return int|bool The ID of the activity on success. False on error.
    10231061 */
    10241062function bp_activity_add( $args = '' ) {
    … …  
    10791117
    10801118/**
    1081  * Post an activity update
     1119 * Post an activity update.
    10821120 *
    10831121 * @since BuddyPress (1.2)
    10841122 *
    1085  * @param array $args See docs for $defaults for details
    1086  *
    1087  * @global object $bp BuddyPress global settings
     1123 * @global object $bp BuddyPress global settings.
    10881124 * @uses wp_parse_args()
    10891125 * @uses bp_is_user_inactive()
    10901126 * @uses bp_core_get_userlink()
    10911127 * @uses bp_activity_add()
    1092  * @uses apply_filters() To call the 'bp_activity_new_update_action' hook
    1093  * @uses apply_filters() To call the 'bp_activity_new_update_content' hook
    1094  * @uses apply_filters() To call the 'bp_activity_new_update_primary_link' hook
     1128 * @uses apply_filters() To call the 'bp_activity_new_update_action' hook.
     1129 * @uses apply_filters() To call the 'bp_activity_new_update_content' hook.
     1130 * @uses apply_filters() To call the 'bp_activity_new_update_primary_link' hook.
    10951131 * @uses bp_update_user_meta()
    10961132 * @uses wp_filter_kses()
    1097  * @uses do_action() To call the 'bp_activity_posted_update' hook
    1098  *
     1133 * @uses do_action() To call the 'bp_activity_posted_update' hook.
     1134 *
     1135 * @param array $args {
     1136 *     @string $content The content of the activity update.
     1137 *     @int $user_id Optional. Defaults to the logged-in user.
     1138 * }
    10991139 * @return int $activity_id The activity id
    11001140 */
    … …  
    11421182
    11431183/**
    1144  * Add an activity comment
     1184 * Add an activity comment.
    11451185 *
    11461186 * @since BuddyPress (1.2)
    11471187 *
    1148  * @param array $args See docs for $defaults for details
    1149  *
    1150  * @global object $bp BuddyPress global settings
     1188 * @global object $bp BuddyPress global settings.
    11511189 * @uses wp_parse_args()
    11521190 * @uses bp_activity_add()
    1153  * @uses apply_filters() To call the 'bp_activity_comment_action' hook
    1154  * @uses apply_filters() To call the 'bp_activity_comment_content' hook
     1191 * @uses apply_filters() To call the 'bp_activity_comment_action' hook.
     1192 * @uses apply_filters() To call the 'bp_activity_comment_content' hook.
    11551193 * @uses bp_activity_new_comment_notification()
    11561194 * @uses wp_cache_delete()
    1157  * @uses do_action() To call the 'bp_activity_comment_posted' hook
    1158  *
    1159  * @return int $comment_id The comment id
     1195 * @uses do_action() To call the 'bp_activity_comment_posted' hook.
     1196 *
     1197 * @param array $args {
     1198 *     @int $id Optional. Pass an ID to update an existing comment.
     1199 *     @string $content The content of the comment.
     1200 *     @int $user_id Optional. The ID of the user making the comment. Defaults
     1201 *                   to the ID of the logged-in user.
     1202 *     @int $activity_id The ID of the "root" activity item, ie the oldest
     1203 *                       ancestor of the comment.
     1204 *     @int $parent_id Optional. The ID of the parent activity item, ie the
     1205 *                     item to which the comment is an immediate reply. If
     1206 *                     not provided, this value defaults to the $activity_id.
     1207 * }
     1208 * @return int|bool The ID of the comment on success, otherwise false.
    11601209 */
    11611210function bp_activity_new_comment( $args = '' ) {
    … …  
    12121261 * @since BuddyPress (1.2)
    12131262 *
    1214  * @param array $args See docs for $defaults for details
    1215  *
     1263 * @see BP_Activity_Activity::get() For more information on accepted arguments.
    12161264 * @uses wp_parse_args()
    1217  * @uses apply_filters() To call the 'bp_activity_get_activity_id' hook
     1265 * @uses apply_filters() To call the 'bp_activity_get_activity_id' hook.
    12181266 * @uses BP_Activity_Activity::save() {@link BP_Activity_Activity}
    12191267 *
    1220  * @return int $activity_id The activity id
     1268 * @param array $args See BP_Activity_Activity::get() for description.
     1269 * @return int $activity_id The ID of the activity item found.
    12211270 */
    12221271function bp_activity_get_activity_id( $args = '' ) {
    … …  
    12391288
    12401289/**
    1241  * Deleting Activity
     1290 * Delete activity item(s).
    12421291 *
    12431292 * If you're looking to hook into one action that provides the ID(s) of
    … …  
    12531302 * @since BuddyPress (1.0)
    12541303 *
    1255  * @param array $args See docs for $defaults for details
    1256  *
     1304 * @see BP_Activity_Activity::get() For more information on accepted arguments.
    12571305 * @uses wp_parse_args()
    12581306 * @uses bp_activity_adjust_mention_count()
    12591307 * @uses BP_Activity_Activity::delete() {@link BP_Activity_Activity}
    1260  * @uses do_action() To call the 'bp_before_activity_delete' hook
     1308 * @uses do_action() To call the 'bp_before_activity_delete' hook.
    12611309 * @uses bp_get_user_meta()
    12621310 * @uses bp_delete_user_meta()
    1263  * @uses do_action() To call the 'bp_activity_delete' hook
    1264  * @uses do_action() To call the 'bp_activity_deleted_activities' hook
     1311 * @uses do_action() To call the 'bp_activity_delete' hook.
     1312 * @uses do_action() To call the 'bp_activity_deleted_activities' hook.
    12651313 * @uses wp_cache_delete()
    12661314 *
    1267  * @return bool True on success, false on failure
     1315 * @param array $args To delete specific activity items, use
     1316 *                        $args = array( 'id' => $ids );
     1317 *                    Otherwise, to use filters for item deletion, the argument
     1318 *                    format is the same as BP_Activity_Activity::get(). See
     1319 *                    that method for a description.
     1320 * @return bool True on success, false on failure.
    12681321 */
    12691322function bp_activity_delete( $args = '' ) {
    … …  
    13161369
    13171370    /**
    1318      * Delete an activity item by activity id
     1371     * Delete an activity item by activity id.
    13191372     *
    1320      * You should use bp_activity_delete() instead
     1373     * You should use bp_activity_delete() instead.
    13211374     *
    13221375     * @since BuddyPress (1.1)
    13231376     * @deprecated BuddyPress (1.2)
    13241377     *
    1325      * @param array $args See docs for $defaults for details
    1326      *
    13271378     * @uses wp_parse_args()
    13281379     * @uses bp_activity_delete()
    13291380     *
    1330      * @return bool True on success, false on failure
     1381     * @param array $args See BP_Activity_Activity::get for a description
     1382     *                    of accepted arguments.
     1383     *
     1384     * @return bool True on success, false on failure.
    13311385     */
    13321386    function bp_activity_delete_by_item_id( $args = '' ) {
    … …  
    13461400
    13471401    /**
    1348      * Delete an activity item by activity id
     1402     * Delete an activity item by activity id.
    13491403     *
    1350      * You should use bp_activity_delete() instead
     1404     * @since BuddyPress (1.1)
     1405     *
     1406     * @uses bp_activity_delete()
     1407     *
     1408     * @param int ID of the activity item to be deleted.
     1409     * @return bool True on success, false on failure.
     1410     */
     1411    function bp_activity_delete_by_activity_id( $activity_id ) {
     1412        return bp_activity_delete( array( 'id' => $activity_id ) );
     1413    }
     1414
     1415    /**
     1416     * Delete an activity item by its content.
     1417     *
     1418     * You should use bp_activity_delete() instead.
    13511419     *
    13521420     * @since BuddyPress (1.1)
    13531421     * @deprecated BuddyPress (1.2)
    13541422     *
    1355      * @param int $activity_id The activity id
    1356      *
    13571423     * @uses bp_activity_delete()
    13581424     *
    1359      * @return bool True on success, false on failure
     1425     * @param int $user_id The user id.
     1426     * @param string $content The activity id.
     1427     * @param string $component The activity component.
     1428     * @param string $type The activity type.
     1429     * @return bool True on success, false on failure.
    13601430     */
    1361     function bp_activity_delete_by_activity_id( $activity_id ) {
    1362         return bp_activity_delete( array( 'id' => $activity_id ) );
     1431    function bp_activity_delete_by_content( $user_id, $content, $component, $type ) {
     1432        return bp_activity_delete( array( 'user_id' => $user_id, 'content' => $content, 'component' => $component, 'type' => $type ) );
    13631433    }
    13641434
    13651435    /**
    1366      * Delete an activity item by it's content
     1436     * Delete a user's activity for a component.
    13671437     *
    1368      * You should use bp_activity_delete() instead
     1438     * You should use bp_activity_delete() instead.
    13691439     *
    13701440     * @since BuddyPress (1.1)
    13711441     * @deprecated BuddyPress (1.2)
    13721442     *
    1373      * @param int $user_id The user id
    1374      * @param string $content The activity id
    1375      * @param string $component The activity component
    1376      * @param string $type The activity type
    1377      *
    13781443     * @uses bp_activity_delete()
    13791444     *
    1380      * @return bool True on success, false on failure
    1381      */
    1382     function bp_activity_delete_by_content( $user_id, $content, $component, $type ) {
    1383         return bp_activity_delete( array( 'user_id' => $user_id, 'content' => $content, 'component' => $component, 'type' => $type ) );
    1384     }
    1385 
    1386     /**
    1387      * Delete a user's activity for a component
    1388      *
    1389      * You should use bp_activity_delete() instead
    1390      *
    1391      * @since BuddyPress (1.1)
    1392      * @deprecated BuddyPress (1.2)
    1393      *
    1394      * @param int $user_id The user id
    1395      * @param string $component The activity component
    1396      *
    1397      * @uses bp_activity_delete()
    1398      *
    1399      * @return bool True on success, false on failure
     1445     * @param int $user_id The user id.
     1446     * @param string $component The activity component.
     1447     * @return bool True on success, false on failure.
    14001448     */
    14011449    function bp_activity_delete_for_user_by_component( $user_id, $component ) {
    … …  
    14041452
    14051453/**
    1406  * Delete an activity comment
     1454 * Delete an activity comment.
    14071455 *
    14081456 * @since BuddyPress (1.2)
    14091457 *
    1410  * @param int $activity_id The activity id
    1411  * @param int $comment_id The activity comment id
    1412  *
    1413  * @uses apply_filters() To call the 'bp_activity_delete_comment_pre' hook
     1458 * @uses apply_filters() To call the 'bp_activity_delete_comment_pre' hook.
    14141459 * @uses bp_activity_delete_children()
    14151460 * @uses bp_activity_delete()
    14161461 * @uses BP_Activity_Activity::rebuild_activity_comment_tree() {@link BP_Activity_Activity}
    1417  * @uses do_action() To call the 'bp_activity_delete_comment' hook
    1418  *
     1462 * @uses do_action() To call the 'bp_activity_delete_comment' hook.
     1463 * @todo Why is an activity id required? We could look this up.
     1464 * @todo Why do we encourage users to call this function directly? We could just
     1465 *       as easily examine the activity type in bp_activity_delete() and then
     1466 *       call this function with the proper arguments if necessary.
     1467 *
     1468 * @param int $activity_id The ID of the "root" activity, ie the comment's
     1469 *                         oldest ancestor.
     1470 * @param int $comment_id The ID of the comment to be deleted.
    14191471 * @return bool True on success, false on failure
    14201472 */
    … …  
    14431495
    14441496    /**
    1445      * Delete an activity comment's children
     1497     * Delete an activity comment's children.
    14461498     *
    14471499     * @since BuddyPress (1.2)
    1448      *
    1449      * @param int $activity_id The activity id
    1450      * @param int $comment_id The activity comment id
    14511500     *
    14521501     * @uses BP_Activity_Activity::get_child_comments() {@link BP_Activity_Activity}
    14531502     * @uses bp_activity_delete_children()
    14541503     * @uses bp_activity_delete()
     1504     *
     1505     * @param int $activity_id The ID of the "root" activity, ie the
     1506     *                         comment's oldest ancestor.
     1507     * @param int $comment_id The ID of the comment to be deleted.
    14551508     */
    14561509    function bp_activity_delete_children( $activity_id, $comment_id) {
    … …  
    14651518
    14661519/**
    1467  * Get the permalink for a single activity item
    1468  *
    1469  * When only the $activity_id param is passed, BP has to instantiate a new BP_Activity_Activity
    1470  * object. To save yourself some processing overhead, be sure to pass the full $activity_obj param
    1471  * as well, if you already have it available.
     1520 * Get the permalink for a single activity item.
     1521 *
     1522 * When only the $activity_id param is passed, BP has to instantiate a new
     1523 * BP_Activity_Activity object. To save yourself some processing overhead,
     1524 * be sure to pass the full $activity_obj parameter as well, if you already
     1525 * have it available.
    14721526 *
    14731527 * @since BuddyPress (1.2)
    1474  *
    1475  * @param int $activity_id The unique id of the activity object
    1476  * @param object $activity_obj (optional) The activity object
    14771528 *
    14781529 * @uses bp_get_root_domain()
    14791530 * @uses bp_get_activity_root_slug()
    1480  * @uses apply_filters_ref_array() To call the 'bp_activity_get_permalink' hook
    1481  *
    1482  * @return string $link Permalink for the activity item
     1531 * @uses apply_filters_ref_array() To call the 'bp_activity_get_permalink' hook.
     1532 *
     1533 * @param int $activity_id The unique id of the activity object.
     1534 * @param object $activity_obj Optional. The activity object.
     1535 * @return string $link Permalink for the activity item.
    14831536 */
    14841537function bp_activity_get_permalink( $activity_id, $activity_obj = false ) {
    … …  
    15051558
    15061559/**
    1507  * Hide a user's activity
     1560 * Hide a user's activity.
    15081561 *
    15091562 * @since BuddyPress (1.2)
    15101563 *
    1511  * @param int $user_id The user id
    1512  *
    15131564 * @uses BP_Activity_Activity::hide_all_for_user() {@link BP_Activity_Activity}
    15141565 *
    1515  * @return bool True on success, false on failure
     1566 * @param int $user_id The ID of the user whose activity is being hidden.
     1567 * @return bool True on success, false on failure.
    15161568 */
    15171569function bp_activity_hide_user_activity( $user_id ) {
    … …  
    15201572
    15211573/**
    1522  * Take content, remove all images and replace them with one thumbnail image.
     1574 * Take content, remove images, and replace them with a single thumbnail image.
     1575 *
     1576 * The format of items in the activity stream is such that we do not want to
     1577 * allow an arbitrary number of arbitrarily large images to be rendered.
     1578 * However, the activity stream is built to elegantly display a single
     1579 * thumbnail corresponding to the activity comment. This function looks
     1580 * through the content, grabs the first image and converts it to a thumbnail,
     1581 * and removes the rest of the images from the string.
    15231582 *
    15241583 * @since BuddyPress (1.2)
    1525  *
    1526  * @param string $content The content to work with
    1527  * @param string $link Optional. The unescaped URL that the image should link to
    1528  * @param array $activity_args Optional. The args passed to the activity
    1529  *   creation function (eg bp_blogs_record_activity())
    15301584 *
    15311585 * @uses esc_attr()
    15321586 * @uses apply_filters() To call the 'bp_activity_thumbnail_content_images' hook
    15331587 *
    1534  * @return string $content The content with images stripped and replaced with a single thumb.
     1588 * @param string $content The content of the activity item.
     1589 * @param string $link Optional. The unescaped URL that the image should link
     1590 *                               to. If absent, the image will not be a link.
     1591 * @param array $activity_args Optional. The args passed to the activity
     1592 *                             creation function (eg bp_blogs_record_activity()).
     1593 * @return string $content The content with images stripped and replaced with a
     1594 *                         single thumb.
    15351595 */
    15361596function bp_activity_thumbnail_content_images( $content, $link = false, $args = false ) {
    … …  
    15761636
    15771637/**
    1578  * Convenience function to control whether the current user is allowed to mark activity items as spam
    1579  *
    1580  * @return bool True if user is allowed to mark activity items as spam
     1638 * Fetch whether the current user is allowed to mark items as spam.
     1639 *
    15811640 * @since BuddyPress (1.6)
    1582  * @static
     1641 *
     1642 * @return bool True if user is allowed to mark activity items as spam.
    15831643 */
    15841644function bp_activity_user_can_mark_spam() {
    … …  
    15871647
    15881648/**
    1589  * Mark activity item as spam
    1590  *
    1591  * @global object $bp BuddyPress global settings
    1592  * @param BP_Activity_Activity $activity
    1593  * @param string $source Optional; default is "by_a_person" (e.g. a person has manually marked the activity as spam).
     1649 * Mark an activity item as spam.
     1650 *
    15941651 * @since BuddyPress (1.6)
     1652 *
     1653 * @global object $bp BuddyPress global settings.
     1654 *
     1655 * @param BP_Activity_Activity $activity The activity item to be spammed.
     1656 * @param string $source Optional. Default is "by_a_person" (ie, a person has
     1657 *                       manually marked the activity as spam). BP core also
     1658 *                       accepts 'by_akismet'.
    15951659 */
    15961660function bp_activity_mark_as_spam( &$activity, $source = 'by_a_person' ) {
    … …  
    16231687
    16241688/**
    1625  * Mark activity item as ham
    1626  *
    1627  * @global object $bp BuddyPress global settings
    1628  * @param BP_Activity_Activity $activity
    1629  * @param string $source Optional; default is "by_a_person" (e.g. a person has manually marked the activity as spam).
     1689 * Mark an activity item as ham.
     1690 *
    16301691 * @since BuddyPress (1.6)
     1692 *
     1693 * @global object $bp BuddyPress global settings.
     1694 *
     1695 * @param BP_Activity_Activity $activity The activity item to be hammed.
     1696 * @param string $source Optional. Default is "by_a_person" (ie, a person has
     1697 *                       manually marked the activity as spam). BP core also
     1698 *                       accepts 'by_akismet'.
    16311699 */
    16321700function bp_activity_mark_as_ham( &$activity, $source = 'by_a_person' ) {
    … …  
    16621730
    16631731/**
    1664  * Grabs the activity update ID and attempts to retrieve the oEmbed cache (if it exists)
    1665  * during the activity loop.  If no cache and link is embeddable, cache it.
     1732 * Set up activity oEmbed cache during the activity loop.
     1733 *
     1734 * During an activity loop, this function sets up the hooks necessary to grab
     1735 * each item's embeds from the cache, or put them in the cache if they are
     1736 * not there yet.
    16661737 *
    16671738 * This does not cover recursive activity comments, as they do not use a real loop.
    … …  
    16731744 * @see bp_embed_activity_cache()
    16741745 * @see bp_embed_activity_save_cache()
    1675  *
    1676  * @uses add_filter() To attach 'bp_get_activity_id' to 'embed_post_id'
    1677  * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'
    1678  * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'
     1746 * @uses add_filter() To attach 'bp_get_activity_id' to 'embed_post_id'.
     1747 * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'.
     1748 * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'.
    16791749 */
    16801750function bp_activity_embed() {
    … …  
    16861756
    16871757/**
    1688  * Grabs the activity comment ID and attempts to retrieve the oEmbed cache (if it exists)
    1689  * when BP is recursing through activity comments {@link bp_activity_recurse_comments()}.
    1690  * If no cache and link is embeddable, cache it.
     1758 * Set up activity oEmbed cache while recursing through activity comments.
     1759 *
     1760 * While crawling through an activity comment tree
     1761 * ({@link bp_activity_recurse_comments}), this function sets up the hooks
     1762 * necessary to grab each comment's embeds from the cache, or put them in
     1763 * the cache if they are not there yet.
    16911764 *
    16921765 * @since BuddyPress (1.5)
    … …  
    16951768 * @see bp_embed_activity_cache()
    16961769 * @see bp_embed_activity_save_cache()
    1697  *
    1698  * @uses add_filter() To attach 'bp_get_activity_comment_id' to 'embed_post_id'
    1699  * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'
    1700  * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'
     1770 * @uses add_filter() To attach 'bp_get_activity_comment_id' to 'embed_post_id'.
     1771 * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'.
     1772 * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'.
    17011773 */
    17021774function bp_activity_comment_embed() {
    … …  
    17131785 *
    17141786 * @see BP_Embed
    1715  *
    1716  * @param object $activity The activity that is being expanded
    1717  *
    17181787 * @global object $bp BuddyPress global settings
    1719  * @uses add_filter() To attach create_function() to 'embed_post_id'
    1720  * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'
    1721  * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'
     1788 * @uses add_filter() To attach create_function() to 'embed_post_id'.
     1789 * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'.
     1790 * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'.
     1791 *
     1792 * @param object $activity The activity that is being expanded.
    17221793 */
    17231794function bp_dtheme_embed_read_more( $activity ) {
    … …  
    17331804
    17341805/**
    1735  * Removes the 'embed_post_id' filter after {@link bp_activity_recurse_comments()}
    1736  * is rendered to avoid conflict with the 'embed_post_id' filter in
    1737  * {@link bp_activity_embed()} or any other component embeds.
     1806 * Clean up 'embed_post_id' filter after comment recursion.
     1807 *
     1808 * This filter must be removed so that the non-comment filters take over again
     1809 * once the comments are done being processed.
    17381810 *
    17391811 * @since BuddyPress (1.5)
    17401812 *
    17411813 * @see bp_activity_comment_embed()
    1742  *
    1743  * @uses remove_filter() To remove 'bp_get_activity_comment_id' from 'embed_post_id'
     1814 * @uses remove_filter() To remove 'bp_get_activity_comment_id' from 'embed_post_id'.
    17441815 */
    17451816function bp_activity_comment_embed_after_recurse() {
    … …  
    17491820
    17501821/**
    1751  * Wrapper function for {@link bp_activity_get_meta()}.
     1822 * Fetch an activity item's cached embeds.
     1823 *
    17521824 * Used during {@link BP_Embed::parse_oembed()} via {@link bp_activity_embed()}.
    17531825 *
    17541826 * @since BuddyPress (1.5)
    17551827 *
     1828 * @see BP_Embed::parse_oembed()
    17561829 * @uses bp_activity_get_meta()
    17571830 *
    1758  * @return mixed The activity meta
     1831 * @param string $cache An empty string passed by BP_Embed::parse_oembed() for
     1832 *                      functions like this one to filter.
     1833 * @param int $id The ID of the activity item.
     1834 * @param string $cachekey The cache key generated in BP_Embed::parse_oembed().
     1835 * @return mixed The cached embeds for this activity item.
    17591836 */
    17601837function bp_embed_activity_cache( $cache, $id, $cachekey ) {
    … …  
    17631840
    17641841/**
    1765  * Wrapper function for {@link bp_activity_update_meta()}.
     1842 * Set an activity item's embed cache.
     1843 *
    17661844 * Used during {@link BP_Embed::parse_oembed()} via {@link bp_activity_embed()}.
    17671845 *
    17681846 * @since BuddyPress (1.5)
    17691847 *
     1848 * @see BP_Embed::parse_oembed()
    17701849 * @uses bp_activity_update_meta()
     1850 *
     1851 * @param string $cache An empty string passed by BP_Embed::parse_oembed() for
     1852 *                      functions like this one to filter.
     1853 * @param int $id The ID of the activity item.
     1854 * @param string $cachekey The cache key generated in BP_Embed::parse_oembed().
     1855 * @return bool True on success, false on failure.
    17711856 */
    17721857function bp_embed_activity_save_cache( $cache, $cachekey, $id ) {
Note: See TracChangeset for help on using the changeset viewer.