Ticket #5936: bp-activity-actions-5936-2.diff

src/bp-activity/bp-activity-actions.php

@@ -15 +15 @@
 /**
  * Allow core components and dependent plugins to register activity actions.
  *
- * @since BuddyPress (1.2)
+ * @since BuddyPress (1.2.0)
  *
  * @uses do_action() To call 'bp_register_activity_actions' hook.
  */
 function bp_register_activity_actions() {
+
+        /**
+         * Fires on bp_init to allow core componants and dependent plugins to register activity actions.
+         *
+         * @since BuddyPress (1.2.0)
+         */
         do_action( 'bp_register_activity_actions' );
 }
 add_action( 'bp_init', 'bp_register_activity_actions', 8 );
@@ -96 +102 @@
                 $redirect = add_query_arg( urlencode_deep( $query_frags ), $redirect );
         }
 
-        // Allow redirect to be filtered
+        /**
+         * Filter the intended redirect url before the redirect occurs for the single activity item.
+         *
+         * @since BuddyPress (1.2.2)
+         *
+         * @param array Array with url to redirect to and activity related to the redirect.
+         */
         if ( ! $redirect = apply_filters_ref_array( 'bp_activity_permalink_redirect_url', array( $redirect, &$activity ) ) ) {
                 bp_core_redirect( bp_get_root_domain() );
         }
@@ -149 +161 @@
         if ( ! bp_activity_user_can_delete( $activity ) )
                 return false;
 
-        // Call the action before the delete so plugins can still fetch information about it
+        /**
+         * Fires before the deletion so plugins can still fetch information about it.
+         *
+         * @since BuddyPress (1.5.0)
+         *
+         * @param int $activity_id The activity ID.
+         * @param int $user_id The user associated with the activity.
+         */
         do_action( 'bp_activity_before_action_delete_activity', $activity_id, $activity->user_id );
 
         // Delete the activity item and provide user feedback
@@ -158 +177 @@
         else
                 bp_core_add_message( __( 'There was an error when deleting that activity', 'buddypress' ), 'error' );
 
+        /**
+         * Fires after the deletion so plugins can act afterwards based on the activity.
+         *
+         * @since BuddyPress (1.1.0)
+         *
+         * @param int $activity_id The activity ID.
+         * @param int $user_id The user associated with the activity.
+         */
         do_action( 'bp_activity_action_delete_activity', $activity_id, $activity->user_id );
 
         // Check for the redirect query arg, otherwise let WP handle things
@@ -203 +230 @@
         // Check nonce
         check_admin_referer( 'bp_activity_akismet_spam_' . $activity->id );
 
-        // Call an action before the spamming so plugins can modify things if they want to
+        /**
+         * Fires before the marking activity as spam so plugins can modify things if they want to.
+         *
+         * @since BuddyPress (1.6.0)
+         *
+         * @param int    $activty_id Activity ID to be marked as spam.
+         * @param object $activity Activity object for the ID to be marked as spam.
+         */
         do_action( 'bp_activity_before_action_spam_activity', $activity->id, $activity );
 
         // Mark as spam
@@ -213 +247 @@
         // Tell the user the spamming has been succesful
         bp_core_add_message( __( 'The activity item has been marked as spam and is no longer visible.', 'buddypress' ) );
 
+        /**
+         * Fires after the marking activity as spam so plugins can act afterwards based on the activity.
+         *
+         * @since BuddyPress (1.6.0)
+         *
+         * @param int $activty_id Activity ID that was marked as spam.
+         * @param int $user_id User ID associated with activity.
+         */
         do_action( 'bp_activity_action_spam_activity', $activity_id, $activity->user_id );
 
         // Check for the redirect query arg, otherwise let WP handle things
@@ -253 +295 @@
         // Check the nonce
         check_admin_referer( 'post_update', '_wpnonce_post_update' );
 
-        // Get activity info
+        /**
+         * Filters the content provided in the activity input field.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $whats-new Activity message being posted.
+         */
         $content = apply_filters( 'bp_activity_post_update_content', $_POST['whats-new'] );
 
         if ( ! empty( $_POST['whats-new-post-object'] ) ) {
+
+                /**
+                 * Filters the item type that the activity update should be associated with.
+                 *
+                 * @since BuddyPress (1.2.0)
+                 *
+                 * @param string $whats-new-post-object Item type to associate with.
+                 */
                 $object = apply_filters( 'bp_activity_post_update_object', $_POST['whats-new-post-object'] );
         }
 
         if ( ! empty( $_POST['whats-new-post-in'] ) ) {
+
+                /**
+                 * Filters what component the activity is being to.
+                 *
+                 * @since BuddyPress (1.2.0)
+                 *
+                 * @param string $whats-new-post-in Chosen component to post activity to.
+                 */
                 $item_id = apply_filters( 'bp_activity_post_update_item_id', $_POST['whats-new-post-in'] );
         }
 
@@ -280 +344 @@
                         $activity_id = groups_post_update( array( 'content' => $content, 'group_id' => $item_id ) );
                 }
 
-        // Special circumstance so let filters handle it
         } else {
+
+                /**
+                 * Filters activity object for BuddyPress core and plugin authors before posting activity update.
+                 *
+                 * @since BuddyPress (1.2.0)
+                 *
+                 * @param string $object Activity item being associated to.
+                 * @param string $item_id Component ID being posted to.
+                 * @param string $content Activity content being posted.
+                 */
                 $activity_id = apply_filters( 'bp_activity_custom_update', $object, $item_id, $content );
         }
 
@@ -322 +395 @@
         // Check the nonce
         check_admin_referer( 'new_activity_comment', '_wpnonce_new_activity_comment' );
 
+        /**
+         * Filters the activity ID a comment will be in reply to.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $comment_form_id ID of the activity being replied to.
+         */
         $activity_id = apply_filters( 'bp_activity_post_comment_activity_id', $_POST['comment_form_id'] );
+
+        /**
+         * Filters the comment content for a comment reply.
+         *
+         * @since BuddyPress (1.2.0)
+         *
+         * @param string $ac_input_activity_id Comment content being posted.
+         */
         $content = apply_filters( 'bp_activity_post_comment_content', $_POST['ac_input_' . $activity_id] );
 
         if ( empty( $content ) ) {
@@ -640 +728 @@
         if ( ! bp_get_option( 'wordpress_api_key' ) && ! defined( 'WPCOM_API_KEY' ) )
                 return;
 
-        // Bail if BuddyPress Activity Akismet support has been disabled by another plugin
+        /**
+         * Filters if BuddyPress Activity Akismet support has been disabled by another plugin.
+         *
+         * @since BuddyPress (1.6.0)
+         *
+         * @param bool bp_is_akismet_active Return value of bp_is_akismet_active boolean function.
+         */
         if ( ! apply_filters( 'bp_activity_use_akismet', bp_is_akismet_active() ) )
                 return;