Merge pull request #191 from 10up/fix/hookdoc-generation

Fix/hookdoc generation

.github/action-release/rsync-filter.txt

@@ -10,11 +10,13 @@
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - CREDITS.md
+- hookdoc-conf.json
 - /ISSUE_TEMPLATE/
 - LICENSE.md
 - PULL_REQUEST_TEMPLATE.md
 - /bin/
 - composer.lock
+- /docs/
 - /node_modules/
 - package-lock.json
 - package.json

.github/workflows/build-docs.yml

@@ -3,7 +3,7 @@ name: Build Hook Docs
 on:
  push:
    branches:
-    - master
+    - develop
 
 jobs:
   build:

.gitignore

@@ -3,6 +3,7 @@ release
 phpunit.xml
 /dist
 coverage
+/docs
 
 debug.log
 

includes/Classifai/Admin/DebugInfo.php

@@ -51,9 +51,14 @@ public function add_classifai_debug_information( $information ) {
 		/**
 		 * Filters debug information displayed on the Site Health screen for the ClassifAI plugin.
 		 *
-		 * @param array Array of associative arrays corresponding to lines shown on the Site Health screen. Each array
-		 *              requires a `label` and a `value` field. Other accepted fields are `debug` and `private`.
 		 * @since 1.4.0
+		 * @hook classifai_debug_information
+		 * @see {@link https://developer.wordpress.org/reference/hooks/debug_information/|debug_information}
+		 *
+		 * @param {array} 'debug_info' Array of associative arrays corresponding to lines shown on the Site Health screen. Each array
+		 *              requires a `label` and a `value` field. Other accepted fields are `debug` and `private`.
+		 *
+		 * @return {array} Filtered array of debug information.
 		 */
 		$fields = apply_filters(
 			'classifai_debug_information',

includes/Classifai/Admin/SavePostHandler.php

@@ -81,11 +81,14 @@ public function classify( $post_id ) {
 		 *
 		 * Default is true, return false to skip classifying a post.
 		 *
-		 * @param bool $should_classify Whether the post should be classified. Default true, return false to skip
+		 * @since 1.2.0
+		 * @hook classifai_should_classify_post
+		 *
+		 * @param {bool} $should_classify Whether the post should be classified. Default `true`, return `false` to skip
 		 *                              classification for this post.
-		 * @param int  $post_id         The id of the post to be considered for classification.
+		 * @param {int}  $post_id         The ID of the post to be considered for classification.
 		 *
-		 * @return bool $should_classify Whether the post should be classified.
+		 * @return {bool} Whether the post should be classified.
 		 */
 		$classifai_should_classify_post = apply_filters( 'classifai_should_classify_post', true, $post_id );
 		if ( ! $classifai_should_classify_post ) {
@@ -193,7 +196,16 @@ public function is_rest_route() {
 			return false;
 		}
 
-		// Support custom post types with custom rest base.
+		/**
+		 * Filter the REST bases. Supports custom post types with a custom REST base.
+		 *
+		 * @since 1.5.0
+		 * @hook classifai_rest_bases
+		 *
+		 * @param {array} rest_bases Array of REST bases.
+		 *
+		 * @return {array} The filtered array of REST bases.
+		 */
 		$rest_bases = apply_filters( 'classifai_rest_bases', array( 'posts', 'pages' ) );
 
 		foreach ( $rest_bases as $rest_base ) {

includes/Classifai/Helpers.php

@@ -195,6 +195,16 @@ function get_supported_post_types() {
 		$post_types = [ 'post' ];
 	}
 
+	/**
+	 * Filter post types supported for language processing.
+	 *
+	 * @since 1.0.0
+	 * @hook classifai_post_types
+	 *
+	 * @param {array} $post_types Array of post types to be classified with language processing.
+	 *
+	 * @return {array} Array of post types.
+	 */
 	$post_types = apply_filters( 'classifai_post_types', $post_types );
 
 	return $post_types;
@@ -259,10 +269,13 @@ function get_feature_threshold( $feature ) {
 	 * Filter the threshold for a specific feature. Any results below the
 	 * threshold will be ignored.
 	 *
-	 * @param string $threshold The threshold to use.
-	 * @param string $feature   The feature whose threshold to lookup.
+	 * @since 1.0.0
+	 * @hook classifai_feature_threshold
 	 *
-	 * @ return string $threshold The filtered threshold.
+	 * @param {string} $threshold The threshold to use, expressed as a decimal between 0 and 1 inclusive.
+	 * @param {string} $feature   The feature in question.
+	 *
+	 * @return {string} The filtered threshold.
 	 */
 	return apply_filters( 'classifai_feature_threshold', $threshold, $feature );
 }
@@ -295,10 +308,13 @@ function get_feature_taxonomy( $feature ) {
 	/**
 	 * Filter the Taxonomy for the specified NLU feature.
 	 *
-	 * @param string $taxonomy The taxonomy to use.
-	 * @param string $feature  The NLU feature this taxonomy is for.
+	 * @since 1.1.0
+	 * @hook classifai_taxonomy_for_feature
+	 *
+	 * @param {string} $taxonomy The slug of the taxonomy to use.
+	 * @param {string} $feature  The NLU feature this taxonomy is for.
 	 *
-	 * @return string $taxonomy The filtered taxonomy.
+	 * @return {string} The filtered taxonomy slug.
 	 */
 	return apply_filters( 'classifai_taxonomy_for_feature', $taxonomy, $feature );
 }
@@ -314,7 +330,12 @@ function computer_vision_max_filesize() {
 	/**
 	 * Filters the Computer Vision maximum allowed filesize.
 	 *
-	 * @param int Default 4MB.
+	 * @since 1.5.0
+	 * @hook classifai_computer_vision_max_filesize
+	 *
+	 * @param {int} file_size The maximum allowed filesize for Computer Vision in bytes. Default `4 * MB_IN_BYTES`.
+	 *
+	 * @return {int} Filtered filesize in bytes.
 	 */
 	return apply_filters( 'classifai_computer_vision_max_filesize', 4 * MB_IN_BYTES ); // 4MB default.
 }

includes/Classifai/Plugin.php

@@ -42,6 +42,12 @@ public function enable() {
 	 * Initializes the ClassifAI plugin modules and support objects.
 	 */
 	public function init() {
+		/**
+		 * Fires before ClassifAI services are loaded.
+		 *
+		 * @since 1.2.0
+		 * @hook before_classifai_init
+		 */
 		do_action( 'before_classifai_init' );
 
 		// Initialize the services, each services handles the providers
@@ -60,6 +66,12 @@ public function init() {
 			);
 		}
 
+		/**
+		 * Fires after ClassifAI services are loaded.
+		 *
+		 * @since 1.2.0
+		 * @hook after_classifai_init
+		 */
 		do_action( 'after_classifai_init' );
 	}
 
@@ -74,6 +86,16 @@ public function i18n() {
 	 * Initialize the Services.
 	 */
 	public function init_services() {
+		/**
+		 * Filter available Services.
+		 *
+		 * @since 1.3.0
+		 * @hook classifai_services
+		 *
+		 * @param {array} 'services' Associative array of service slugs and PHP class namespace.
+		 *
+		 * @return {array} The filtered list of services.
+		 */
 		$classifai_services = apply_filters(
 			'classifai_services',
 			[

includes/Classifai/Providers/Azure/ComputerVision.php

@@ -150,10 +150,13 @@ public function smart_crop_image( $metadata, $attachment_id ) {
 		 * Filters whether to apply smart cropping to the current image.
 		 *
 		 * @since 1.5.0
+		 * @hook classifai_should_smart_crop_image
 		 *
-		 * @param boolean Whether to apply smart cropping. The default value is set in ComputerVision settings.
-		 * @param array   Image metadata.
-		 * @param int     The attachment ID.
+		 * @param {bool}  $should_smart_crop Whether to apply smart cropping. The default value is set in ComputerVision settings.
+		 * @param {array} $metadata          Image metadata.
+		 * @param {int}   $attachment_id     The attachment ID.
+		 *
+		 * @return {bool} Whether to apply smart cropping.
 		 */
 		if ( ! apply_filters( 'classifai_should_smart_crop_image', $should_smart_crop, $metadata, $attachment_id ) ) {
 			return $metadata;
@@ -282,9 +285,12 @@ protected function generate_alt_tags( $captions, $attachment_id ) {
 		/**
 		 * Filter the captions returned from the API.
 		 *
-		 * @param array $captions. The caption data.
+		 * @since 1.4.0
+		 * @hook classifai_computer_vision_captions
+		 *
+		 * @param {array} $captions The returned caption data.
 		 *
-		 * @return array $captions The filtered caption data.
+		 * @return {array} The filtered caption data.
 		 */
 		$captions = apply_filters( 'classifai_computer_vision_captions', $captions );
 		// If $captions isn't an array, don't save them.
@@ -296,10 +302,13 @@ protected function generate_alt_tags( $captions, $attachment_id ) {
 				$rtn = $captions[0]->text;
 			} else {
 				/**
-				 * Fire an action if there were no captions added.
+				 * Fires if there were no captions returned.
+				 *
+				 * @since 1.5.0
+				 * @hook classifai_computer_vision_caption_failed
 				 *
-				 * @param array $tags.   The caption data.
-				 * @param int $threshold The caption_threshold setting.
+				 * @param array $tags      The caption data.
+				 * @param int   $threshold The caption_threshold setting.
 				 */
 				do_action( 'classifai_computer_vision_caption_failed', $captions, $threshold );
 			}
@@ -322,9 +331,12 @@ protected function generate_image_tags( $tags, $attachment_id ) {
 		/**
 		 * Filter the tags returned from the API.
 		 *
-		 * @param array $tags. The image tag data.
+		 * @since 1.4.0
+		 * @hook classifai_computer_vision_image_tags
 		 *
-		 * @return array $tags The filtered image tags.
+		 * @param {array} $tags The image tag data.
+		 *
+		 * @return {array} The filtered image tags.
 		 */
 		$tags = apply_filters( 'classifai_computer_vision_image_tags', $tags );
 		// If $tags isn't an array, don't save them.
@@ -343,10 +355,13 @@ protected function generate_image_tags( $tags, $attachment_id ) {
 				wp_update_term_count_now( $custom_tags, $taxonomy );
 			} else {
 				/**
-				 * Fire an action if there were no tags added.
+				 * Fires if there were no tags added.
+				 *
+				 * @since 1.5.0
+				 * @hook classifai_computer_vision_image_tag_failed
 				 *
-				 * @param array $tags.   The image tag data.
-				 * @param int $threshold The tag_threshold setting.
+				 * @param array $tags      The image tag data.
+				 * @param int   $threshold The tag_threshold setting.
 				 */
 				do_action( 'classifai_computer_vision_image_tag_failed', $tags, $threshold );
 			}

includes/Classifai/Providers/Azure/SmartCropping.php

@@ -79,8 +79,11 @@ public function get_wp_filesystem() {
 		 * Filters the filesystem class instance used to save image files.
 		 *
 		 * @since 1.5.0
+		 * @hook classifai_smart_crop_wp_filesystem
 		 *
-		 * @param WP_Filesystem_Base
+		 * @param {WP_Filesystem_Base} $this->wp_filesystem Filesystem class for saving images.
+		 *
+		 * @return {WP_Filesystem_Base} Filtered Filesystem class.
 		 */
 		return apply_filters( 'classifai_smart_crop_wp_filesystem', $this->wp_filesystem );
 	}
@@ -97,7 +100,12 @@ public function get_max_pixel_dimension() {
 		/**
 		 * Filters the maximum allowable width or height of an image to be cropped. Default 1024.
 		 *
-		 * @param int The width/height in pixels.
+		 * @since 1.5.0
+		 * @hook classifai_smart_crop_max_pixel_dimension
+		 *
+		 * @param {int} max The max width/height in pixels.
+		 *
+		 * @return {int} Filtered max dimension in pixels.
 		 */
 		return apply_filters( 'classifai_smart_crop_max_pixel_dimension', 1024 );
 	}
@@ -139,9 +147,12 @@ public function should_crop( $size ) {
 		 * Filters whether to smart crop images of a given size.
 		 *
 		 * @since 1.5.0
+		 * @hook classifai_should_crop_size
+		 *
+		 * @param {bool}   $return Whether non-position-based cropping was opted into when registering the image size.
+		 * @param {string} $size   The image size.
 		 *
-		 * @param boolean Whether non-position-based cropping was opted into when registering the image size.
-		 * @param string  The image size.
+		 * @return {bool} Whether this image size should be smart cropped.
 		 */
 		return apply_filters( 'classifai_should_crop_size', $return, $size );
 	}
@@ -194,9 +205,12 @@ public function get_cropped_thumbnail( $attachment_id, $size_data ) {
 		 * plugin behavior.
 		 *
 		 * @since 1.5.0
+		 * @hook classifai_smart_cropping_source_url
+		 *
+		 * @param {null|string} url            `null` to use default plugin behavior; `string` to override.
+		 * @param {int}         $attachment_id The attachment image ID.
 		 *
-		 * @param null|string Null to use default plugin behavior; string to override.
-		 * @param int         The attachment image ID.
+		 * @return {null|string} URL to be sent to Computer Vision for smart cropping.
 		 */
 		$url = apply_filters( 'classifai_smart_cropping_source_url', null, $attachment_id );
 
@@ -312,6 +326,7 @@ public function request_cropped_thumbnail( $data ) {
 		 * Fires after the request to the generateThumbnail smart-cropping endpoint has run.
 		 *
 		 * @since 1.5.0
+		 * @hook classifai_smart_cropping_after_request
 		 *
 		 * @param array|WP_Error Response data or a WP_Error if the request failed.
 		 * @param string The request URL with query args added.
@@ -327,6 +342,7 @@ public function request_cropped_thumbnail( $data ) {
 		 * Fires when the generateThumbnail smart-cropping API response did not have a 200 status code.
 		 *
 		 * @since 1.5.0
+		 * @hook classifai_smart_cropping_unsuccessful_response
 		 *
 		 * @param array|WP_Error Response data or a WP_Error if the request failed.
 		 * @param string The request URL with query args added.

includes/Classifai/Services/Service.php

@@ -45,7 +45,14 @@ public function __construct( $display_name, $menu_slug, $providers ) {
 	 */
 	public function init() {
 		/**
-		 * Filter the list of providers
+		 * Filter the list of providers for the service.
+		 *
+		 * @since 1.3.0
+		 * @hook {$this->menu_slug}_providers
+		 *
+		 * @param {array} $this->providers Array of available providers for the service.
+		 *
+		 * @return {array} The filtered available providers.
 		 */
 		$this->providers = apply_filters( "{$this->menu_slug}_providers", $this->providers );
 

includes/Classifai/Watson/Classifier.php

@@ -69,9 +69,12 @@ public function classify( $text, $options = [], $request_options = [] ) {
 		/**
 		 * Filter the classified data returned from the API call.
 		 *
-		 * @param array $classified_data The classified data.
+		 * @since 1.0.0
+		 * @hook classifai_classified_data
 		 *
-		 * @return array $classified_data The filtered classified data.
+		 * @param {array} $classified_data The classified data.
+		 *
+		 * @return {array} The filtered classified data.
 		 */
 		return apply_filters( 'classifai_classified_data', $classified_data );
 	}

includes/Classifai/Watson/Normalizer.php

@@ -59,13 +59,15 @@ public function normalize_content( $post_content, $post_title = '', $post_id = f
 		}
 
 		/**
-		 * Filters the normalized content to allow for additional
-		 * cleanup.
+		 * Filters the normalized content to allow for additional cleanup.
 		 *
 		 * @since 0.1.0
+		 * @hook classifai_normalize
 		 *
-		 * @param string $post_content The normalized post_content
-		 * @param int $post_id The ID of the post whose content is being normalized
+		 * @param {string} $post_content The normalized post content.
+		 * @param {int}    $post_id      The ID of the post whose content is being normalized.
+		 *
+		 * @return {string} The filtered normalized post content.
 		 */
 		$post_content = apply_filters( 'classifai_normalize', $post_content, $post_id );