Merge pull request #448 from 10up/feature/hook-docs

Generate Hook Docs with a GitHub Action

distributor.php

@@ -156,6 +156,7 @@ function() {
 			 * Filter whether the network connection type is enabled. Enabled by default, return false to disable.
 			 *
 			 * @since 1.0.0
+			 * @hook dt_network_site_connection_enabled
 			 *
 			 * @param bool true Whether the network connection should be enabled.
 			 */

hookdoc-conf.json

@@ -0,0 +1,13 @@
+{
+  "opts": {
+      "destination": "docs",
+      "template": "node_modules/wp-hookdoc/template",
+      "recurse": true
+  },
+  "source": {
+      "includePattern": ".+\\.(php|inc)?$"
+  },
+  "plugins": [
+    "node_modules/wp-hookdoc/plugin"
+  ]
+}

includes/.github/workflows/build-docs.yml

@@ -0,0 +1,29 @@
+name: Node CI
+
+on: push:
+ branches:
+ - develop
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    node-version: [12.x]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: npm install, and build docs
+      run: |
+        npm install
+        npm run build:docs
+      env:
+        CI: true
+  deploy:
+    - name: GitHub Pages Deploy
+    - uses: maxheld83/[email protected]
+    - env:
+        BUILD_DIR = "docs/"
+        secrets = ["GH_PAT"]

includes/classes/API/SubscriptionsController.php

@@ -286,6 +286,7 @@ public function receive_item( $request ) {
 			 * Action fired after receiving a subscription update from Distributor
 			 *
 			 * @since 1.3.8
+			 * @hook dt_process_subscription_attributes
 			 *
 			 * @param WP_Post         $post    Updated post object.
 			 * @param WP_REST_Request $request Request object.

includes/classes/Authentication.php

@@ -51,6 +51,7 @@ public function format_get_args( $args = array(), $context = array() ) {
 		 * Format request args for a GET request so auth occurs
 		 *
 		 * @since 0.8
+		 * @hook dt_auth_format_get_args
 		 *
 		 * @param  array  $args
 		 * @param  array  $context optional array of information about the request
@@ -72,6 +73,7 @@ public function format_post_args( $args, $context = array() ) {
 		 * Format request args for a POST request so auth occurs
 		 *
 		 * @since 0.8
+		 * @hook dt_auth_format_post_args
 		 *
 		 * @param  array  $args
 		 * @param  array  $context optional array of information about the request

includes/classes/Authentications/WordPressBasicAuth.php

@@ -118,6 +118,7 @@ public static function prepare_credentials( $args ) {
 		 * Filter the authorization credentials prepared before saving.
 		 *
 		 * @since 1.0
+		 * @hook dt_auth_prepare_credentials
 		 *
 		 * @param array  $auth The credentials to be saved.
 		 * @param array  $args The arguments originally passed to .prepare_credentials'.

includes/classes/Authentications/WordPressDotcomOauth2Authentication.php

@@ -51,7 +51,7 @@ class WordPressDotcomOauth2Authentication extends Authentication {
 	public static function credentials_form( $args = array() ) {
 
 		// Check if we need to display the form, or request a token?
-		$code = isset( $_GET['code'] ) ? sanitize_text_field( wp_unslash( $_GET['code'] ) ) : false; // Input var okay. WPCS: CSRF ok.
+		$code = isset( $_GET['code'] ) ? sanitize_text_field( wp_unslash( $_GET['code'] ) ) : false; // @codingStandardsIgnoreLine Nonce not required.
 
 		/**
 		 * A code is present as a query parameter in the URL when the user has authorized the connection
@@ -89,6 +89,7 @@ public static function credentials_form( $args = array() ) {
 		$args[ self::API_REDIRECT_URI ] = $redirect_uri;
 
 		// Display any authorization or token errors.
+		// @hook dt_oauth_admin_notices
 		do_action( 'dt_oauth_admin_notices' );
 
 		// If anything is missing, we aren't authorized - show the credentials form.
@@ -258,7 +259,7 @@ public static function prepare_credentials( $args ) {
 		if ( ! empty( $args['dt_created_post_id'] ) ) {
 			$auth['dt_created_post_id'] = sanitize_text_field( $args['dt_created_post_id'] );
 		}
-
+		// Filter documented in includes/classes/Authentications/WordPressBasicAuth.php.
 		return apply_filters( 'dt_auth_prepare_credentials', $auth, $args, self::$slug );
 	}
 

includes/classes/ExternalConnection.php

@@ -96,6 +96,7 @@ public function log_sync( array $item_id_mappings, $connection_id = 0 ) {
 		 * Action fired when a sync is being logged.
 		 *
 		 * @since 1.0
+		 * @hook dt_log_sync
 		 *
 		 * @param array $item_id_mappings Item ID mappings.
 		 * @param array $sync_log The sync log

includes/classes/ExternalConnections/WordPressExternalConnection.php

@@ -119,18 +119,15 @@ public function remote_get( $args = array() ) {
 			$query_args['page']        = ( empty( $args['paged'] ) ) ? 1 : $args['paged'];
 
 			if ( isset( $args['post__in'] ) ) {
+				// If post__in is empty, we can just stop right here
 				if ( empty( $args['post__in'] ) ) {
-					// If post__in is empty, we can just stop right here
 					/**
-					 * Filter the remote_get request
+					 * Filter the remote_get request.
 					 *
 					 * @since 1.0
+					 * @hook dt_remote_get
 					 *
-					 * @param array  $args {
-					 *      @type array Items to get.
-					 *      @type int Total number of items to get.
-					 * }
-					 * @param  array  $args The arguments originally passed to .remote_get'.
+					 * @param array $args The arguments originally passed to remote_get.
 					 * @param  object $this The authentication class.
 					 */
 					return apply_filters(
@@ -235,6 +232,7 @@ public function remote_get( $args = array() ) {
 		 * Filter the remote_get query arguments
 		 *
 		 * @since 1.0
+		 * @hook dt_remote_get_query_args
 		 *
 		 * @param  array  $query_args The existing query arguments.
 		 * @param  array  $args       The arguments originally passed to .remote_get'.
@@ -292,6 +290,7 @@ public function remote_get( $args = array() ) {
 				 * Filter the URL that remote_get will use
 				 *
 				 * @since 1.0
+				 * @hook dt_remote_get_url
 				 *
 				 * @param  string $posts_url  The posts URL
 				 * @param  string $args       The arguments originally passed to .remote_get'.
@@ -416,6 +415,7 @@ public function pull( $items ) {
 			 * Filter the arguments passed into wp_insert_post during a pull.
 			 *
 			 * @since 1.0
+			 * @hook dt_pull_post_args
 			 *
 			 * @param  array              $post_array                     The post to be inserted.
 			 * @param  array              $item_array['remote_post_id']   The remote post ID.
@@ -469,6 +469,8 @@ public function pull( $items ) {
 			/**
 			 * Action triggered when a post is pulled via distributor.
 			 *
+			 * @hook dt_pull_post
+			 *
 			 * @param int                $new_post   The newly created post ID.
 			 * @param ExternalConnection $this       The distributor connection pulling the post.
 			 * @param array              $post_array The original post data retrieved via the connection.
@@ -636,6 +638,8 @@ public function push( $post_id, $args = array() ) {
 		/**
 		 * Action triggered when a post is pushed via distributor.
 		 *
+		 * @hook dt_push_post
+		 *
 		 * @param array              $response   The HTTP response of the push.
 		 * @param array              $post_body  The body that was POSTed.
 		 * @param string             $type_url   The URL that was POSTed to.

includes/classes/InternalConnections/NetworkSiteConnection.php

@@ -111,7 +111,7 @@ public function push( $post_id, $args = array() ) {
 		}
 
 		add_filter( 'wp_insert_post_data', array( '\Distributor\InternalConnections\NetworkSiteConnection', 'maybe_set_modified_date' ), 10, 2 );
-
+		// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
 		$new_post_id = wp_insert_post( apply_filters( 'dt_push_post_args', $new_post_args, $post, $args, $this ) );
 
 		remove_filter( 'wp_insert_post_data', array( '\Distributor\InternalConnections\NetworkSiteConnection', 'maybe_set_modified_date' ), 10, 2 );
@@ -132,6 +132,8 @@ public function push( $post_id, $args = array() ) {
 			/**
 			 * Allow bypassing of all media processing.
 			 *
+			 * @hook dt_push_post_media
+			 *
 			 * @param bool                  true           If Distributor should set the post media.
 			 * @param int                   $new_post_id   The newly created post ID.
 			 * @param array                 $media         List of media items attached to the post, formatted by {@see \Distributor\Utils\prepare_media()}.
@@ -147,6 +149,8 @@ public function push( $post_id, $args = array() ) {
 		/**
 		 * Action triggered when a post is pushed via distributor.
 		 *
+		 * @hook dt_push_post
+		 *
 		 * @param int                $new_post_id   The newly created post ID.
 		 * @param int                $post_id       The original post ID.
 		 * @param array              $args          The arguments passed into wp_insert_post.
@@ -211,6 +215,7 @@ public function pull( $items ) {
 
 			add_filter( 'wp_insert_post_data', array( '\Distributor\InternalConnections\NetworkSiteConnection', 'maybe_set_modified_date' ), 10, 2 );
 
+			// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
 			$new_post_id = wp_insert_post( apply_filters( 'dt_pull_post_args', $post_array, $item_array['remote_post_id'], $post, $this ) );
 
 			remove_filter( 'wp_insert_post_data', array( '\Distributor\InternalConnections\NetworkSiteConnection', 'maybe_set_modified_date' ), 10, 2 );
@@ -231,6 +236,8 @@ public function pull( $items ) {
 				/**
 				 * Allow bypassing of all media processing.
 				 *
+				 * @hook dt_pull_post_media
+				 *
 				 * @param bool                  true                          If Distributor should set the post media.
 				 * @param int                   $new_post_id                  The newly created post ID.
 				 * @param array                 $post->media                  List of media items attached to the post, formatted by {@see \Distributor\Utils\prepare_media()}.
@@ -271,6 +278,7 @@ public function pull( $items ) {
 			 * Action triggered when a post is pulled via distributor.
 			 *
 			 * @since 1.0
+			 * @hook dt_pull_post
 			 *
 			 * @param int                $new_post_id   The new post ID that was pulled.
 			 * @param ExternalConnection $this          The distributor connection pulling the post.
@@ -325,6 +333,7 @@ public function log_sync( array $item_id_mappings, $blog_id = 0 ) {
 		 * Action fired when a sync is being logged.
 		 *
 		 * @since 1.0
+		 * @hook dt_log_sync
 		 *
 		 * @param array $item_id_mappings Item ID mappings.
 		 * @param array $sync_log The sync log
@@ -370,6 +379,7 @@ public function remote_get( $args = array() ) {
 					// If post__in is empty, we can just stop right here
 					restore_current_blog();
 
+					// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
 					return apply_filters(
 						'dt_remote_get',
 						[
@@ -407,6 +417,7 @@ public function remote_get( $args = array() ) {
 				$query_args['order'] = $args['order'];
 			}
 
+			// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
 			$posts_query = new \WP_Query( apply_filters( 'dt_remote_get_query_args', $query_args, $args, $this ) );
 
 			$posts = $posts_query->posts;
@@ -424,6 +435,7 @@ public function remote_get( $args = array() ) {
 
 			restore_current_blog();
 
+			// Filter documented in /includes/classes/ExternalConnections/WordPressExternalConnection.php.
 			return apply_filters(
 				'dt_remote_get',
 				[
@@ -450,6 +462,7 @@ public function remote_get( $args = array() ) {
 
 			restore_current_blog();
 
+			// Filter documented in /includes/classes/ExternalConnections/WordPressExternalConnection.php.
 			return apply_filters( 'dt_remote_get', $formatted_post, $args, $this );
 		}
 	}
@@ -647,15 +660,15 @@ public static function get_available_authorized_sites( $context = null ) {
 		}
 
 		/**
-		 * Allow plugins to override the default {@see \Distributor\InternalConnections\NetworkSiteConnection::get_available_authorized_sites()} function.
+		 * Enable plugins to filter the authorized sites, before they are retrieved.
 		 *
 		 * @since 1.2
 		 * @since 1.3.7 Added the `$context` parameter.
+		 * @hook dt_pre_get_authorized_sites
+		 *
+		 * @see \Distributor\InternalConnections\NetworkSiteConnection::get_available_authorized_sites()
 		 *
-		 * @param array  $authorized_sites {
-		 *     @type array {
-		 *         'site'       => $site,  // WP_Site object.
-		 *         'post_types' => $array, // List of post type objects the user can edit.
+		 * @param array  $authorized_sites Array of WP_Site object and post type objects the user can edit.
 		 * }
 		 * @param string $context The context of the authorization.
 		 */
@@ -671,11 +684,9 @@ public static function get_available_authorized_sites( $context = null ) {
 		 *
 		 * @since 1.2
 		 * @since 1.3.7 Added the `$context` parameter.
+		 * @hook dt_authorized_sites
 		 *
-		 * @param array  $authorized_sites {
-		 *     @type array {
-		 *         'site'       => $site,  // WP_Site object.
-		 *         'post_types' => $array, // List of post type objects the user can edit.
+		 * @param array  $authorized_sites An array of WP_Site objects and the post type objects the user can edit.
 		 * }
 		 * @param string $context The context of the authorization.
 		 */

includes/classes/PullListTable.php

@@ -136,6 +136,7 @@ protected function bulk_actions( $which = '' ) {
 			 * This filter can currently only be used to remove bulk actions.
 			 *
 			 * @since 3.5.0
+			 * @hook bulk_actions-{$this->screen->id}
 			 *
 			 * @param array $actions An array of the available bulk actions.
 			 */
@@ -243,8 +244,10 @@ public function column_date( $post ) {
 			}
 			echo '<br />';
 			if ( 'excerpt' === $mode ) {
+				// Core filter, documented in wp-admin/includes/class-wp-posts-list-table.php.
 				echo esc_html( apply_filters( 'post_date_column_time', $t_time, $post, 'date', $mode ) );
 			} else {
+				// Core filter, documented in wp-admin/includes/class-wp-posts-list-table.php.
 				echo '<abbr title="' . esc_attr( $t_time ) . '">' . esc_html( apply_filters( 'post_date_column_time', $h_time, $post, 'date', $mode ) ) . '</abbr>';
 			}
 		}
@@ -562,6 +565,7 @@ public function extra_tablenav( $which ) {
 		 * Action fired when extra table nav is generated.
 		 *
 		 * @since 1.0
+		 * @hook dt_pull_filters
 		 */
 		do_action( 'dt_pull_filters' );
 	}

includes/external-connection-cpt.php

@@ -573,6 +573,7 @@ function add_menu_item() {
 		 * Filter Distributor capabilities allowed to view external connections.
 		 *
 		 * @since 1.0.0
+		 * @hook dt_capabilities
 		 *
 		 * @param string manage_options The capability allowed to view external connections.
 		 */
@@ -601,6 +602,7 @@ function add_submenu_item() {
 		 * Filter Distributor capabilities allowed to manage external connections.
 		 *
 		 * @since 1.0.0
+		 * @hook dt_external_capabilities
 		 *
 		 * @param string manage_options The capability allowed to manage external connections.
 		 */

includes/pull-ui.php

@@ -132,6 +132,7 @@ function action_admin_menu() {
 		 * Filter Distributor capabilities allowed to pull content.
 		 *
 		 * @since 1.0.0
+		 * @hook dt_pull_capabilities
 		 *
 		 * @param string manage_options The capability allowed to pull content.
 		 */
@@ -189,6 +190,7 @@ function process_actions() {
 				exit;
 			}
 
+			// Filter documented above.
 			if ( ! current_user_can( apply_filters( 'dt_pull_capabilities', 'manage_options' ) ) ) {
 				wp_die(
 					'<h1>' . esc_html__( 'Cheatin&#8217; uh?', 'distributor' ) . '</h1>' .
@@ -257,6 +259,7 @@ function( $remote_post_id ) use ( $post_type ) {
 				exit;
 			}
 
+			// Filter documented above.
 			if ( ! current_user_can( apply_filters( 'dt_pull_capabilities', 'manage_options' ) ) ) {
 				wp_die(
 					'<h1>' . esc_html__( 'Cheatin&#8217; uh?', 'distributor' ) . '</h1>' .