Improving docblocks on hooks throughout plugin

Author: frankiejarrett

classes/class-wp-stream-api.php

@@ -325,6 +325,18 @@ protected function remote_request( $url = '', $args = array(), $allow_cache = tr
 		}
 
 		if ( ! is_wp_error( $request ) ) {
+			/**
+			 * Filter the request data of the API response.
+			 *
+			 * Does not fire on non-blocking requests.
+			 *
+			 * @since 2.0.0
+			 *
+			 * @param string $url
+			 * @param array  $args
+			 *
+			 * @return array
+			 */
 			$data = apply_filters( 'wp_stream_api_request_data', json_decode( $request['body'] ), $url, $args );
 
 			// Loose comparison needed

classes/class-wp-stream-author.php

@@ -223,6 +223,13 @@ static function get_current_agent() {
 			$agent = 'wp_cron';
 		}
 
+		/**
+		 * Filter the current agent string
+		 *
+		 * @since 1.4.4
+		 *
+		 * @return string
+		 */
 		$agent = apply_filters( 'wp_stream_current_agent', $agent );
 
 		return $agent;
@@ -241,6 +248,15 @@ static function get_agent_label( $agent ) {
 			$label = '';
 		}
 
+		/**
+		 * Filter agent labels
+		 *
+		 * @since 1.4.4
+		 *
+		 * @param string $agent
+		 *
+		 * @return string
+		 */
 		$label = apply_filters( 'wp_stream_agent_label', $label, $agent );
 
 		return $label;

classes/class-wp-stream-db.php

@@ -41,7 +41,7 @@ public function store( $records ) {
 		/**
 		 * Allows modification of record information just before logging occurs.
 		 *
-		 * @since 0.0.2
+		 * @since 0.2.0
 		 *
 		 * @param  array $records An array of record data.
 		 */
@@ -57,9 +57,12 @@ public function store( $records ) {
 		$result = $this->insert( $records );
 
 		if ( $result && ! is_wp_error( $result ) ) {
+
 			/**
 			 * Fires when A Post is inserted
 			 *
+			 * @since 2.0.0
+			 *
 			 * @param  int    $record_id  Inserted record ID
 			 * @param  array  $recordarr  Array of information on this record
 			 */
@@ -106,6 +109,8 @@ public function query( $query, $fields ) {
 		/**
 		 * Allows developers to change the final result set of records
 		 *
+		 * @since 2.0.0
+		 *
 		 * @param array $results
 		 * @param array $query
 		 * @param array $fields

classes/class-wp-stream-log.php

@@ -18,8 +18,9 @@ public static function load() {
 		/**
 		 * Filter allows developers to change log handler class
 		 *
-		 * @param  array   Current Class
-		 * @return string  New Class for log handling
+		 * @since 0.2.0
+		 *
+		 * @return string  Class name to use for log handling
 		 */
 		$log_handler = apply_filters( 'wp_stream_log_handler', __CLASS__ );
 
@@ -236,6 +237,8 @@ public static function debug_backtrace( $recordarr ) {
 		 * use the available $recordarr parameter to specify what types of records to
 		 * create backtrace logs for.
 		 *
+		 * @since 2.0.2
+		 *
 		 * @param array $recordarr
 		 *
 		 * @return bool  Set to FALSE by default (backtrace disabled)

classes/class-wp-stream-query.php

@@ -73,6 +73,8 @@ public function query( $args ) {
 		/**
 		 * Filter allows additional query properties to be added
 		 *
+		 * @since 2.0.0
+		 *
 		 * @return array  Array of query properties
 		 */
 		$properties = apply_filters( 'wp_stream_query_properties', $properties );
@@ -91,6 +93,8 @@ public function query( $args ) {
 		/**
 		 * Filter allows additional arguments to query $args
 		 *
+		 * @since 1.4.0
+		 *
 		 * @return array  Array of query arguments
 		 */
 		$args = apply_filters( 'wp_stream_query_args', $args );
@@ -249,13 +253,17 @@ public function query( $args ) {
 		/**
 		 * Filter allows the final query args to be modified
 		 *
+		 * @since 2.0.0
+		 *
 		 * @return array  Array of query arguments
 		 */
 		$query = apply_filters( 'wp_stream_db_query', $query );
 
 		/**
 		 * Filter allows the final query fields to be modified
 		 *
+		 * @since 2.0.0
+		 *
 		 * @return array  Array of query fields
 		 */
 		$fields = apply_filters( 'wp_stream_db_fields', $fields );

stream.php

@@ -103,6 +103,8 @@ private function __construct() {
 		/**
 		 * Filter allows a custom Stream API class to be instantiated
 		 *
+		 * @since 2.0.2
+		 *
 		 * @return object  The API class object
 		 */
 		self::$api = apply_filters( 'wp_stream_api_class', new WP_Stream_API );
@@ -133,6 +135,7 @@ private function __construct() {
 		// Add frontend indicator
 		add_action( 'wp_head', array( $this, 'frontend_indicator' ) );
 
+		// Load admin area classes
 		if ( is_admin() ) {
 			add_action( 'init', array( 'WP_Stream_Admin', 'load' ) );
 			add_action( 'init', array( 'WP_Stream_Dashboard_Widget', 'load' ) );
@@ -143,16 +146,21 @@ private function __construct() {
 	}
 
 	/**
-	 * Invoked when the PHP version check fails. Load up the translations and
-	 * add the error message to the admin notices
+	 * Invoked when the PHP version check fails
+	 *
+	 * Load up the translations and add the error message to the admin notices.
+	 *
+	 * @return void
 	 */
 	public static function fail_php_version() {
 		add_action( 'plugins_loaded', array( __CLASS__, 'i18n' ) );
 		self::notice( __( 'Stream requires PHP version 5.3+, plugin is currently NOT ACTIVE.', 'stream' ) );
 	}
 
 	/**
+	 * Check for deprecated extension plugins
 	 *
+	 * @return bool
 	 */
 	public static function deprecated_plugins_exist() {
 		foreach ( self::$deprecated_extensions as $class => $dir ) {
@@ -165,7 +173,9 @@ public static function deprecated_plugins_exist() {
 	}
 
 	/**
+	 * Display admin notices when deprecated extension plugins exist
 	 *
+	 * @return void
 	 */
 	public static function deprecated_plugins_notice() {
 		add_action( 'plugins_loaded', array( __CLASS__, 'i18n' ) );
@@ -209,11 +219,12 @@ public static function deprecated_plugins_notice() {
 	}
 
 	/**
-	* Autoloader for classes
-	*
-	* @param  string $class
-	* @return void
-	*/
+	 * Autoloader for classes
+	 *
+	 * @param string $class
+	 *
+	 * @return void
+	 */
 	function autoload( $class ) {
 		$class      = strtolower( str_replace( '_', '-', $class ) );
 		$class_file = sprintf( '%sclass-%s.php', WP_STREAM_CLASS_DIR, $class );
@@ -226,8 +237,8 @@ function autoload( $class ) {
 	/**
 	 * Loads the translation files.
 	 *
-	 * @access public
 	 * @action plugins_loaded
+	 *
 	 * @return void
 	 */
 	public static function i18n() {
@@ -269,6 +280,8 @@ public static function is_development_mode() {
 		/**
 		 * Filter allows development mode to be overridden
 		 *
+		 * @since 2.0.0
+		 *
 		 * @return bool
 		 */
 		return apply_filters( 'wp_stream_development_mode', $development_mode );
@@ -279,6 +292,7 @@ public static function is_development_mode() {
 	 *
 	 * @param string $message
 	 * @param bool $is_error
+	 *
 	 * @return void
 	 */
 	public static function notice( $message, $is_error = true ) {
@@ -305,6 +319,7 @@ public static function notice( $message, $is_error = true ) {
 	 * Show an error or other message in the WP Admin
 	 *
 	 * @action shutdown
+	 *
 	 * @return void
 	 */
 	public static function admin_notices() {
@@ -336,9 +351,8 @@ public static function admin_notices() {
 	 * Displays an HTML comment in the frontend head to indicate that Stream is activated,
 	 * and which version of Stream is currently in use.
 	 *
-	 * @since 1.4.5
-	 *
 	 * @action wp_head
+	 *
 	 * @return string|void An HTML comment, or nothing if the value is filtered out.
 	 */
 	public function frontend_indicator() {
@@ -348,6 +362,8 @@ public function frontend_indicator() {
 		 * Filter allows the HTML output of the frontend indicator comment
 		 * to be altered or removed, if desired.
 		 *
+		 * @since 1.4.5
+		 *
 		 * @return string  The content of the HTML comment
 		 */
 		$comment = apply_filters( 'wp_stream_frontend_indicator', $comment );