Context Navigation

← Previous Change
Next Change →

bp-activity-functions.php

Timestamp:

09/06/2011 12:30:01 PM (15 years ago)

Author:

boonebgorges

Message:

Adds PHPDoc throughout the activity component. References #2345. Turbo props cnorris23

File:

: 1 edited

trunk/bp-activity/bp-activity-functions.php (modified) (41 diffs)

Legend:

: Unmodified
: Added
: Removed

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

-                      r4961
+                      r5109
 <?php
 /**
  * BuddyPress Activity Functions
 …
+ *
  * @package BuddyPress
  * @subpackage Activity Core
+ * @subpackage ActivityFunctions
  */
 …
  * Checks $bp pages global and looks for directory page
+ *
+ * @since 1.5
+ *
+ * @global object $bp Global BuddyPress settings object
+ * @since 1.5.0
+ *
+ * @global object $bp BuddyPress global settings
+ *
  * @return bool True if set, False if empty
  */
 …
  * Searches through the content of an activity item to locate usernames, designated by an @ sign
+ *
  * @package BuddyPress Activity
  * @since 1.5
+ *
  * @param str $content The content of the activity, usually found in $activity->content
  * @return array $usernames Array of the found usernames that match existing users
+ * @since 1.5.0
+ *
+ * @param string $content The content of the activity, usually found in $activity->content
+ *
+ * @return bool|array $usernames Array of the found usernames that match existing users. False if no matches
  */
 function bp_activity_find_mentions( $content ) {
 …
  * Resets a user's unread mentions list and count
+ *
+ * @package BuddyPress Activity
+ * @since 1.5
+ * @since 1.5.0
+ *
  * @param int $user_id The id of the user whose unread mentions are being reset
+ * @uses bp_delete_user_meta()
  */
 function bp_activity_clear_new_mentions( $user_id ) {
 …
  * Adjusts new mention count for mentioned users when activity items are deleted or created
+ *
+ * @package BuddyPress Activity
+ * @since 1.5
+ * @since 1.5.0
+ *
  * @param int $activity_id The unique id for the activity item
+ * @param string $action Can be 'delete' or 'add'. Defaults to 'add'
+ *
+ * @uses BP_Activity_Activity() {@link BP_Activity_Activity}
+ * @uses bp_activity_find_mentions()
+ * @uses bp_is_username_compatibility_mode()
+ * @uses bp_core_get_userid_from_nicename()
+ * @uses bp_get_user_meta()
+ * @uses bp_update_user_meta()
  */
 function bp_activity_adjust_mention_count( $activity_id, $action = 'add' ) {
 …
  * Formats notifications related to activity
+ *
+ * @package BuddyPress Activity
+ * @param str $action The type of activity item. Just 'new_at_mention' for now
+ * @since 1.5.0
+ *
+ * @param string $action The type of activity item. Just 'new_at_mention' for now
  * @param int $item_id The activity id
  * @param int $secondary_item_id In the case of at-mentions, this is the mentioner's id
  * @param int $total_items The total number of notifications to format
+ * @param str $format 'string' to get a BuddyBar-compatible notification, 'array' otherwise
+ * @param string $format 'string' to get a BuddyBar-compatible notification, 'array' otherwise
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses bp_loggedin_user_domain()
+ * @uses bp_get_activity_slug()
+ * @uses bp_core_get_user_displayname()
+ * @uses apply_filters() To call the 'bp_activity_multiple_at_mentions_notification' hook
+ * @uses apply_filters() To call the 'bp_activity_single_at_mentions_notification' hook
+ * @uses do_action() To call 'activity_format_notifications' hook
+ *
+ * @return string $return Formatted @mention notification
  */
 function bp_activity_format_notifications( $action, $item_id, $secondary_item_id, $total_items, $format = 'string' ) {
 …
+}
 /** Actions *******************************************************************/
+/** Actions ******************************************************************/
 /**
  * Sets the current action for a given activity stream location
+ *
+ * @global obj $bp
+ * @param str $component_id
+ * @param str $key
+ * @param str $value
+ * @return bool False on error, True on success
+ * @since 1.1.0
+ *
+ * @param string $component_id
+ * @param string $key
+ * @param string $value
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses apply_filters() To call the 'bp_activity_set_action' hook
+ *
+ * @return bool False if any param is empty, otherwise true
  */
 function bp_activity_set_action( $component_id, $key, $value ) {
 …
  * Retreives the current action from a component and key
+ *
+ * @global obj $bp
+ * @param str $component_id
+ * @param str $key
+ * @since 1.1.0
+ *
+ * @param string $component_id
+ * @param string $key
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses apply_filters() To call the 'bp_activity_get_action' hook
+ *
  * @return mixed False on error, action on success
  */
 …
+}
 /** Favorites *****************************************************************/
+/** Favorites ****************************************************************/
 /**
  * Get a users favorite activity stream items
+ *
+ * @global obj $bp
+ * @since 1.2.0
+ *
  * @param int $user_id
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses bp_get_user_meta()
+ * @uses apply_filters() To call the 'bp_activity_get_user_favorites' hook
+ *
  * @return array Array of users favorite activity stream ID's
  */
 …
  * Add an activity stream item as a favorite for a user
+ *
+ * @global obj $bp
+ * @since 1.2.0
+ *
  * @param int $activity_id
  * @param int $user_id
+ * @return bool
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses is_user_logged_in()
+ * @uses bp_get_user_meta()
+ * @uses bp_activity_get_meta()
+ * @uses bp_update_user_meta()
+ * @uses bp_activity_update_meta()
+ * @uses do_action() To call the 'bp_activity_add_user_favorite' hook
+ * @uses do_action() To call the 'bp_activity_add_user_favorite_fail' hook
+ *
+ * @return bool True on success, false on failure
  */
 function bp_activity_add_user_favorite( $activity_id, $user_id = 0 ) {
 …
+}
+/**
+ * Remove an activity stream item as a favorite for a user
+ *
+ * @since 1.2.0
+ *
+ * @param int $activity_id
+ * @param int $user_id
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses is_user_logged_in()
+ * @uses bp_get_user_meta()
+ * @uses bp_activity_get_meta()
+ * @uses bp_activity_update_meta()
+ * @uses bp_update_user_meta()
+ * @uses do_action() To call the 'bp_activity_remove_user_favorite' hook
+ *
+ * @return bool True on success, false on failure
+ */
 function bp_activity_remove_user_favorite( $activity_id, $user_id = 0 ) {
     global $bp;
 …
  * Check if activity exists by scanning content
+ *
+ * @param str $content
+ * @since 1.1.0
+ *
+ * @param string $content
+ *
+ * @uses BP_Activity_Activity::check_exists_by_content() {@link BP_Activity_Activity}
+ * @uses apply_filters() To call the 'bp_activity_check_exists_by_content' hook
+ *
  * @return bool
  */
 …
 /**
+ * Retreive the last time activity was updated
+ *
+ * @return str
+ * Retrieve the last time activity was updated
+ *
+ * @since 1.0.0
+ *
+ * @uses BP_Activity_Activity::get_last_updated() {@link BP_Activity_Activity}
+ * @uses apply_filters() To call the 'bp_activity_get_last_updated' hook
+ *
+ * @return string Date last updated
  */
 function bp_activity_get_last_updated() {
 …
 /**
+ * Retreive the number of favorite activity stream items a user has
+ *
+ * @global obj $bp
+ * Retrieve the number of favorite activity stream items a user has
+ *
+ * @since 1.2.0
+ *
  * @param int $user_id
+ * @return int
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses BP_Activity_Activity::total_favorite_count() {@link BP_Activity_Activity}
+ *
+ * @return int Total favorite count
  */
 function bp_activity_total_favorites_for_user( $user_id = 0 ) {
 …
+}
 /** Meta **********************************************************************/
+/** Meta *********************************************************************/
 /**
  * Delete a meta entry from the DB for an activity stream item
+ *
  * @global DB $wpdb
  * @global obj $bp
+ * @since 1.2.0
+ *
  * @param int $activity_id
+ * @param str $meta_key
+ * @param str $meta_value
+ * @return bool
+ * @param string $meta_key
+ * @param string $meta_value
+ *
+ * @global object $wpdb
+ * @global object $bp BuddyPress global settings
+ * @uses wp_cache_delete()
+ * @uses is_wp_error()
+ *
+ * @return bool True on success, false on failure
  */
 function bp_activity_delete_meta( $activity_id, $meta_key = '', $meta_value = '' ) {
 …
  * Get activity meta
+ *
  * @global DB $wpdb
  * @global obj $bp
+ * @since 1.2.0
+ *
  * @param int $activity_id
+ * @param str $meta_key
+ * @param string $meta_key
+ *
+ * @global object $wpdb
+ * @global object $bp BuddyPress global settings
+ * @uses wp_cache_get()
+ * @uses wp_cache_set()
+ * @uses apply_filters() To call the 'bp_activity_get_meta' hook
+ *
  * @return bool
  */
 …
  * Update activity meta
+ *
  * @global DB $wpdb
  * @global obj $bp
+ * @since 1.2.0
+ *
  * @param int $activity_id
+ * @param str $meta_key
+ * @param str $meta_value
+ * @return bool
+ * @param string $meta_key
+ * @param string $meta_value
+ *
+ * @global object $wpdb
+ * @global object $bp BuddyPress global settings
+ * @uses maybe_serialize()
+ * @uses bp_activity_delete_meta()
+ * @uses wp_cache_set()
+ *
+ * @return bool True on success, false on failure
  */
 function bp_activity_update_meta( $activity_id, $meta_key, $meta_value ) {
 …
+}
+/** Clean up ******************************************************************/
+/**
+ * Completely remove
+/** Clean up *****************************************************************/
+/**
+ * Completely remove a user's activity data
+ *
+ * @since 1.5.0
+ *
  * @param int $user_id
+ *
+ * @uses is_user_logged_in()
+ * @uses bp_activity_delete()
+ * @uses bp_delete_user_meta()
+ * @uses do_action() To call the 'bp_activity_remove_data' hook
+ * @uses do_action() To call the 'bp_activity_remove_all_user_data' hook
  */
 function bp_activity_remove_all_user_data( $user_id = 0 ) {
 …
  * Register the activity stream actions for updates
+ *
+ * @global obj $bp
+ * @since 1.2.0
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses bp_activity_set_action()
+ * @uses do_action() To call the 'updates_register_activity_actions' hook
  */
 function updates_register_activity_actions() {
 …
 add_action( 'bp_register_activity_actions', 'updates_register_activity_actions' );
 /*******************************************************************************
+/******************************************************************************
  * Business functions are where all the magic happens in BuddyPress. They will
  * handle the actual saving or manipulation of information. Usually they will
 …
  */
+/**
+ * Retrieve an activity or activities
+ *
+ * @since 1.2.0
+ *
+ * @param array $args
+ *
+ * @uses wp_parse_args()
+ * @uses wp_cache_get()
+ * @uses wp_cache_set()
+ * @uses BP_Activity_Activity::get() {@link BP_Activity_Activity}
+ * @uses apply_filters_ref_array() To call the 'bp_activity_get' hook
+ *
+ * @return object $activity The activity/activities object
+ */
 function bp_activity_get( $args = '' ) {
     $defaults = array(
 …
  * Fetch specific activity items
+ *
  * @package BuddyPress
+ * @since 1.2.0
+ *
  * @param array $args See docs for $defaults for details
+ *
+ * @uses wp_parse_args()
+ * @uses apply_filters() To call the 'bp_activity_get_specific' hook
+ * @uses BP_Activity_Activity::get() {@link BP_Activity_Activity}
+ *
  * @return array The array returned by BP_Activity_Activity::get()
  */
 …
+}
+/**
+ * Add an activity item
+ *
+ * @since 1.1.0
+ *
+ * @param array $args See docs for $defaults for details
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses wp_parse_args()
+ * @uses BP_Activity_Activity::save() {@link BP_Activity_Activity}
+ * @uses BP_Activity_Activity::rebuild_activity_comment_tree() {@link BP_Activity_Activity}
+ * @uses wp_cache_delete()
+ * @uses do_action() To call the 'bp_activity_add' hook
+ *
+ * @return int The activity id
+ */
 function bp_activity_add( $args = '' ) {
     global $bp;
 …
+}
+/**
+ * Post an activity update
+ *
+ * @since 1.2.0
+ *
+ * @param array $args See docs for $defaults for details
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses wp_parse_args()
+ * @uses bp_core_is_user_spammer()
+ * @uses bp_core_is_user_deleted()
+ * @uses bp_core_get_userlink()
+ * @uses bp_activity_add()
+ * @uses apply_filters() To call the 'bp_activity_new_update_action' hook
+ * @uses apply_filters() To call the 'bp_activity_new_update_content' hook
+ * @uses apply_filters() To call the 'bp_activity_new_update_primary_link' hook
+ * @uses bp_update_user_meta()
+ * @uses wp_filter_kses()
+ * @uses do_action() To call the 'bp_activity_posted_update' hook
+ *
+ * @return int $activity_id The activity id
+ */
 function bp_activity_post_update( $args = '' ) {
     global $bp;
 …
+}
+/**
+ * Add an activity comment
+ *
+ * @since 1.2.0
+ *
+ * @param array $args See docs for $defaults for details
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses wp_parse_args()
+ * @uses bp_activity_add()
+ * @uses apply_filters() To call the 'bp_activity_comment_action' hook
+ * @uses apply_filters() To call the 'bp_activity_comment_content' hook
+ * @uses bp_activity_new_comment_notification()
+ * @uses wp_cache_delete()
+ * @uses do_action() To call the 'bp_activity_comment_posted' hook
+ *
+ * @return int $comment_id The comment id
+ */
 function bp_activity_new_comment( $args = '' ) {
     global $bp;
 …
 /**
- * bp_activity_get_activity_id()
+ *
  * Fetch the activity_id for an existing activity entry in the DB.
+ *
+ * @package BuddyPress Activity
+ * @since 1.2.0
+ *
+ * @param array $args See docs for $defaults for details
+ *
+ * @uses wp_parse_args()
+ * @uses apply_filters() To call the 'bp_activity_get_activity_id' hook
+ * @uses BP_Activity_Activity::save() {@link BP_Activity_Activity}
+ *
+ * @return int $activity_id The activity id
  */
 function bp_activity_get_activity_id( $args = '' ) {
 …
+}
 /***
+/**
  * Deleting Activity
+ *
 …
+ *
  * If you are deleting an activity comment please use bp_activity_delete_comment();
+*/
+ *
+ * @since 1.0.0
+ *
+ * @param array $args See docs for $defaults for details
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses wp_parse_args()
+ * @uses bp_activity_adjust_mention_count()
+ * @uses BP_Activity_Activity::delete() {@link BP_Activity_Activity}
+ * @uses do_action() To call the 'bp_before_activity_delete' hook
+ * @uses bp_get_user_meta()
+ * @uses bp_delete_user_meta()
+ * @uses do_action() To call the 'bp_activity_delete' hook
+ * @uses do_action() To call the 'bp_activity_deleted_activities' hook
+ * @uses wp_cache_delete()
+ *
+ * @return bool True on success, false on failure
+ */
 function bp_activity_delete( $args = '' ) {
     global $bp;
 …
     return true;
+}
+    // The following functions have been deprecated in place of bp_activity_delete()
+    /**
+     * Delete an activity item by activity id
+     *
+     * You should use bp_activity_delete() instead
+     *
+     * @since 1.1.0
+     * @deprecated 1.2.0
+     *
+     * @param array $args See docs for $defaults for details
+     *
+     * @global object $bp BuddyPress global settings
+     * @uses wp_parse_args()
+     * @uses bp_activity_delete()
+     *
+     * @return bool True on success, false on failure
+     */
     function bp_activity_delete_by_item_id( $args = '' ) {
         global $bp;
 …
+    }
+    /**
+     * Delete an activity item by activity id
+     *
+     * You should use bp_activity_delete() instead
+     *
+     * @since 1.1.0
+     * @deprecated 1.2.0
+     *
+     * @param int $activity_id The activity id
+     *
+     * @uses bp_activity_delete()
+     *
+     * @return bool True on success, false on failure
+     */
     function bp_activity_delete_by_activity_id( $activity_id ) {
         return bp_activity_delete( array( 'id' => $activity_id ) );
+    }
+    /**
+     * Delete an activity item by it's content
+     *
+     * You should use bp_activity_delete() instead
+     *
+     * @since 1.1.0
+     * @deprecated 1.2.0
+     *
+     * @param int $user_id The user id
+     * @param string $content The activity id
+     * @param string $component The activity component
+     * @param string $type The activity type
+     *
+     * @uses bp_activity_delete()
+     *
+     * @return bool True on success, false on failure
+     */
     function bp_activity_delete_by_content( $user_id, $content, $component, $type ) {
         return bp_activity_delete( array( 'user_id' => $user_id, 'content' => $content, 'component' => $component, 'type' => $type ) );
+    }
+    /**
+     * Delete a user's activity for a component
+     *
+     * You should use bp_activity_delete() instead
+     *
+     * @since 1.1.0
+     * @deprecated 1.2.0
+     *
+     * @param int $user_id The user id
+     * @param string $component The activity component
+     *
+     * @uses bp_activity_delete()
+     *
+     * @return bool True on success, false on failure
+     */
     function bp_activity_delete_for_user_by_component( $user_id, $component ) {
         return bp_activity_delete( array( 'user_id' => $user_id, 'component' => $component ) );
+    }
+    // End deprecation
+/**
+ * Delete an activity comment
+ *
+ * @since 1.2.0
+ *
+ * @param int $activity_id The activity id
+ * @param int $comment_id The activity comment id
+ *
+ * @uses apply_filters() To call the 'bp_activity_delete_comment_pre' hook
+ * @uses bp_activity_delete_children()
+ * @uses bp_activity_delete()
+ * @uses BP_Activity_Activity::rebuild_activity_comment_tree() {@link BP_Activity_Activity}
+ * @uses do_action() To call the 'bp_activity_delete_comment' hook
+ *
+ * @return bool True on success, false on failure
+ */
 function bp_activity_delete_comment( $activity_id, $comment_id ) {
     /***
 …
     return true;
+}
+    /**
+     * Delete an activity comment's children
+     *
+     * @since 1.2.0
+     *
+     * @param int $activity_id The activity id
+     * @param int $comment_id The activity comment id
+     *
+     * @uses BP_Activity_Activity::get_child_comments() {@link BP_Activity_Activity}
+     * @uses bp_activity_delete_children()
+     * @uses bp_activity_delete()
+     */
     function bp_activity_delete_children( $activity_id, $comment_id) {
         // Recursively delete all children of this comment.
 …
  * as well, if you already have it available.
+ *
+ * @package BuddyPress
+ *
+ * @uses apply_filters_ref_array() Filter 'bp_activity_get_permalink' to modify the function output
+ * @since 1.2.0
+ *
  * @param int $activity_id The unique id of the activity object
+ * @param obj $activity_obj (optional) The activity object
+ * @return str $link Permalink for the activity item
+ * @param object $activity_obj (optional) The activity object
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses bp_get_root_domain()
+ * @uses bp_get_activity_root_slug()
+ * @uses apply_filters_ref_array() To call the 'bp_activity_get_permalink' hook
+ *
+ * @return string $link Permalink for the activity item
  */
 function bp_activity_get_permalink( $activity_id, $activity_obj = false ) {
 …
+}
+/**
+ * Hide a user's activity
+ *
+ * @since 1.2.0
+ *
+ * @param int $user_id The user id
+ *
+ * @uses BP_Activity_Activity::hide_all_for_user() {@link BP_Activity_Activity}
+ *
+ * @return bool True on success, false on failure
+ */
 function bp_activity_hide_user_activity( $user_id ) {
     return BP_Activity_Activity::hide_all_for_user( $user_id );
 …
 /**
- * bp_activity_thumbnail_content_images()
+ *
  * Take content, remove all images and replace them with one thumbnail image.
+ *
+ * @package BuddyPress Activity
+ * @param $content str - The content to work with
+ * @param $link str - Optional. The URL that the image should link to
+ * @return $content str - The content with images stripped and replaced with a single thumb.
+ * @since 1.2.0
+ *
+ * @param string $content The content to work with
+ * @param string $link Optional. The URL that the image should link to
+ *
+ * @uses esc_attr()
+ * @uses apply_filters() To call the 'bp_activity_thumbnail_content_images' hook
+ *
+ * @return string $content The content with images stripped and replaced with a single thumb.
  */
 function bp_activity_thumbnail_content_images( $content, $link = false ) {
 …
  * For that, see {@link bp_activity_comment_embed()}.
+ *
+ * @since 1.5
+ *
  * @see BP_Embed
  * @see bp_embed_activity_cache()
  * @see bp_embed_activity_save_cache()
+ * @package BuddyPress Activity
+ * @since 1.5
+ *
+ * @uses add_filter() To attach 'bp_get_activity_id' to 'embed_post_id'
+ * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'
+ * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'
  */
 function bp_activity_embed() {
 …
  * If no cache and link is embeddable, cache it.
+ *
+ * @since 1.5
+ *
  * @see BP_Embed
  * @see bp_embed_activity_cache()
  * @see bp_embed_activity_save_cache()
+ * @package BuddyPress Activity
+ * @since 1.5
+ *
+ * @uses add_filter() To attach 'bp_get_activity_comment_id' to 'embed_post_id'
+ * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'
+ * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'
  */
 function bp_activity_comment_embed() {
 …
  * When a user clicks on a "Read More" item, make sure embeds are correctly parsed and shown for the expanded content.
+ *
  * @global object $bp BuddyPress global settings
  * @param BP_Activity_Activity $activity The activity that is being expanded
+ * @since 1.5
+ *
  * @see BP_Embed
+ * @since 1.5
+ *
+ * @param object $activity The activity that is being expanded
+ *
+ * @global object $bp BuddyPress global settings
+ * @uses add_filter() To attach create_function() to 'embed_post_id'
+ * @uses add_filter() To attach 'bp_embed_activity_cache' to 'bp_embed_get_cache'
+ * @uses add_action() To attach 'bp_embed_activity_save_cache' to 'bp_embed_update_cache'
  */
 function bp_dtheme_embed_read_more( $activity ) {
 …
  * {@link bp_activity_embed()} or any other component embeds.
+ *
+ * @since 1.5
+ *
  * @see bp_activity_comment_embed()
  * @package BuddyPress Activity
  * @since 1.5
+ *
+ * @uses remove_filter() To remove 'bp_get_activity_comment_id' from 'embed_post_id'
  */
 function bp_activity_comment_embed_after_recurse() {
 …
  * Used during {@link BP_Embed::parse_oembed()} via {@link bp_activity_embed()}.
+ *
- * @package BuddyPress Activity
  * @since 1.5
+ *
+ * @uses bp_activity_get_meta()
+ *
+ * @return mixed The activity meta
  */
 function bp_embed_activity_cache( $cache, $id, $cachekey ) {
 …
  * Used during {@link BP_Embed::parse_oembed()} via {@link bp_activity_embed()}.
+ *
- * @package BuddyPress Activity
  * @since 1.5
+ *
+ * @uses bp_activity_update_meta()
  */
 function bp_embed_activity_save_cache( $cache, $cachekey, $id ) {

Note: See TracChangeset for help on using the changeset viewer.

Trac UI Preferences

BuddyPress.org

Context Navigation

Changeset 5109 for trunk/bp-activity/bp-activity-functions.php

Legend:

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

Download in other formats: