Skip to content

Commit b1dd60f

Browse files
author
Adam Silverstein
authored
Merge pull request #448 from 10up/feature/hook-docs
Generate Hook Docs with a GitHub Action
2 parents e025c7d + bf2fa9b commit b1dd60f

21 files changed

+318
-27
lines changed

‎distributor.php

+1
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,7 @@ function() {
156156
* Filter whether the network connection type is enabled. Enabled by default, return false to disable.
157157
*
158158
* @since 1.0.0
159+
* @hook dt_network_site_connection_enabled
159160
*
160161
* @param bool true Whether the network connection should be enabled.
161162
*/

‎hookdoc-conf.json

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"opts": {
3+
"destination": "docs",
4+
"template": "node_modules/wp-hookdoc/template",
5+
"recurse": true
6+
},
7+
"source": {
8+
"includePattern": ".+\\.(php|inc)?$"
9+
},
10+
"plugins": [
11+
"node_modules/wp-hookdoc/plugin"
12+
]
13+
}

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

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Node CI
2+
3+
on: push:
4+
branches:
5+
- develop
6+
7+
jobs:
8+
build:
9+
10+
runs-on: ubuntu-latest
11+
node-version: [12.x]
12+
steps:
13+
- uses: actions/checkout@v1
14+
- name: Use Node.js ${{ matrix.node-version }}
15+
uses: actions/setup-node@v1
16+
with:
17+
node-version: ${{ matrix.node-version }}
18+
- name: npm install, and build docs
19+
run: |
20+
npm install
21+
npm run build:docs
22+
env:
23+
CI: true
24+
deploy:
25+
- name: GitHub Pages Deploy
26+
- uses: maxheld83/[email protected]
27+
- env:
28+
BUILD_DIR = "docs/"
29+
secrets = ["GH_PAT"]

‎includes/classes/API/SubscriptionsController.php

+1
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,7 @@ public function receive_item( $request ) {
286286
* Action fired after receiving a subscription update from Distributor
287287
*
288288
* @since 1.3.8
289+
* @hook dt_process_subscription_attributes
289290
*
290291
* @param WP_Post $post Updated post object.
291292
* @param WP_REST_Request $request Request object.

‎includes/classes/Authentication.php

+2
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ public function format_get_args( $args = array(), $context = array() ) {
5151
* Format request args for a GET request so auth occurs
5252
*
5353
* @since 0.8
54+
* @hook dt_auth_format_get_args
5455
*
5556
* @param array $args
5657
* @param array $context optional array of information about the request
@@ -72,6 +73,7 @@ public function format_post_args( $args, $context = array() ) {
7273
* Format request args for a POST request so auth occurs
7374
*
7475
* @since 0.8
76+
* @hook dt_auth_format_post_args
7577
*
7678
* @param array $args
7779
* @param array $context optional array of information about the request

‎includes/classes/Authentications/WordPressBasicAuth.php

+1
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,7 @@ public static function prepare_credentials( $args ) {
118118
* Filter the authorization credentials prepared before saving.
119119
*
120120
* @since 1.0
121+
* @hook dt_auth_prepare_credentials
121122
*
122123
* @param array $auth The credentials to be saved.
123124
* @param array $args The arguments originally passed to .prepare_credentials'.

‎includes/classes/Authentications/WordPressDotcomOauth2Authentication.php

+3-2
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ class WordPressDotcomOauth2Authentication extends Authentication {
5151
public static function credentials_form( $args = array() ) {
5252

5353
// Check if we need to display the form, or request a token?
54-
$code = isset( $_GET['code'] ) ? sanitize_text_field( wp_unslash( $_GET['code'] ) ) : false; // Input var okay. WPCS: CSRF ok.
54+
$code = isset( $_GET['code'] ) ? sanitize_text_field( wp_unslash( $_GET['code'] ) ) : false; // @codingStandardsIgnoreLine Nonce not required.
5555

5656
/**
5757
* 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() ) {
8989
$args[ self::API_REDIRECT_URI ] = $redirect_uri;
9090

9191
// Display any authorization or token errors.
92+
// @hook dt_oauth_admin_notices
9293
do_action( 'dt_oauth_admin_notices' );
9394

9495
// If anything is missing, we aren't authorized - show the credentials form.
@@ -258,7 +259,7 @@ public static function prepare_credentials( $args ) {
258259
if ( ! empty( $args['dt_created_post_id'] ) ) {
259260
$auth['dt_created_post_id'] = sanitize_text_field( $args['dt_created_post_id'] );
260261
}
261-
262+
// Filter documented in includes/classes/Authentications/WordPressBasicAuth.php.
262263
return apply_filters( 'dt_auth_prepare_credentials', $auth, $args, self::$slug );
263264
}
264265

‎includes/classes/ExternalConnection.php

+1
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ public function log_sync( array $item_id_mappings, $connection_id = 0 ) {
9696
* Action fired when a sync is being logged.
9797
*
9898
* @since 1.0
99+
* @hook dt_log_sync
99100
*
100101
* @param array $item_id_mappings Item ID mappings.
101102
* @param array $sync_log The sync log

‎includes/classes/ExternalConnections/WordPressExternalConnection.php

+11-7
Original file line numberDiff line numberDiff line change
@@ -119,18 +119,15 @@ public function remote_get( $args = array() ) {
119119
$query_args['page'] = ( empty( $args['paged'] ) ) ? 1 : $args['paged'];
120120

121121
if ( isset( $args['post__in'] ) ) {
122+
// If post__in is empty, we can just stop right here
122123
if ( empty( $args['post__in'] ) ) {
123-
// If post__in is empty, we can just stop right here
124124
/**
125-
* Filter the remote_get request
125+
* Filter the remote_get request.
126126
*
127127
* @since 1.0
128+
* @hook dt_remote_get
128129
*
129-
* @param array $args {
130-
* @type array Items to get.
131-
* @type int Total number of items to get.
132-
* }
133-
* @param array $args The arguments originally passed to .remote_get'.
130+
* @param array $args The arguments originally passed to remote_get.
134131
* @param object $this The authentication class.
135132
*/
136133
return apply_filters(
@@ -235,6 +232,7 @@ public function remote_get( $args = array() ) {
235232
* Filter the remote_get query arguments
236233
*
237234
* @since 1.0
235+
* @hook dt_remote_get_query_args
238236
*
239237
* @param array $query_args The existing query arguments.
240238
* @param array $args The arguments originally passed to .remote_get'.
@@ -292,6 +290,7 @@ public function remote_get( $args = array() ) {
292290
* Filter the URL that remote_get will use
293291
*
294292
* @since 1.0
293+
* @hook dt_remote_get_url
295294
*
296295
* @param string $posts_url The posts URL
297296
* @param string $args The arguments originally passed to .remote_get'.
@@ -416,6 +415,7 @@ public function pull( $items ) {
416415
* Filter the arguments passed into wp_insert_post during a pull.
417416
*
418417
* @since 1.0
418+
* @hook dt_pull_post_args
419419
*
420420
* @param array $post_array The post to be inserted.
421421
* @param array $item_array['remote_post_id'] The remote post ID.
@@ -469,6 +469,8 @@ public function pull( $items ) {
469469
/**
470470
* Action triggered when a post is pulled via distributor.
471471
*
472+
* @hook dt_pull_post
473+
*
472474
* @param int $new_post The newly created post ID.
473475
* @param ExternalConnection $this The distributor connection pulling the post.
474476
* @param array $post_array The original post data retrieved via the connection.
@@ -636,6 +638,8 @@ public function push( $post_id, $args = array() ) {
636638
/**
637639
* Action triggered when a post is pushed via distributor.
638640
*
641+
* @hook dt_push_post
642+
*
639643
* @param array $response The HTTP response of the push.
640644
* @param array $post_body The body that was POSTed.
641645
* @param string $type_url The URL that was POSTed to.

‎includes/classes/InternalConnections/NetworkSiteConnection.php

+21-10
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ public function push( $post_id, $args = array() ) {
111111
}
112112

113113
add_filter( 'wp_insert_post_data', array( '\Distributor\InternalConnections\NetworkSiteConnection', 'maybe_set_modified_date' ), 10, 2 );
114-
114+
// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
115115
$new_post_id = wp_insert_post( apply_filters( 'dt_push_post_args', $new_post_args, $post, $args, $this ) );
116116

117117
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() ) {
132132
/**
133133
* Allow bypassing of all media processing.
134134
*
135+
* @hook dt_push_post_media
136+
*
135137
* @param bool true If Distributor should set the post media.
136138
* @param int $new_post_id The newly created post ID.
137139
* @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() ) {
147149
/**
148150
* Action triggered when a post is pushed via distributor.
149151
*
152+
* @hook dt_push_post
153+
*
150154
* @param int $new_post_id The newly created post ID.
151155
* @param int $post_id The original post ID.
152156
* @param array $args The arguments passed into wp_insert_post.
@@ -211,6 +215,7 @@ public function pull( $items ) {
211215

212216
add_filter( 'wp_insert_post_data', array( '\Distributor\InternalConnections\NetworkSiteConnection', 'maybe_set_modified_date' ), 10, 2 );
213217

218+
// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
214219
$new_post_id = wp_insert_post( apply_filters( 'dt_pull_post_args', $post_array, $item_array['remote_post_id'], $post, $this ) );
215220

216221
remove_filter( 'wp_insert_post_data', array( '\Distributor\InternalConnections\NetworkSiteConnection', 'maybe_set_modified_date' ), 10, 2 );
@@ -231,6 +236,8 @@ public function pull( $items ) {
231236
/**
232237
* Allow bypassing of all media processing.
233238
*
239+
* @hook dt_pull_post_media
240+
*
234241
* @param bool true If Distributor should set the post media.
235242
* @param int $new_post_id The newly created post ID.
236243
* @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 ) {
271278
* Action triggered when a post is pulled via distributor.
272279
*
273280
* @since 1.0
281+
* @hook dt_pull_post
274282
*
275283
* @param int $new_post_id The new post ID that was pulled.
276284
* @param ExternalConnection $this The distributor connection pulling the post.
@@ -325,6 +333,7 @@ public function log_sync( array $item_id_mappings, $blog_id = 0 ) {
325333
* Action fired when a sync is being logged.
326334
*
327335
* @since 1.0
336+
* @hook dt_log_sync
328337
*
329338
* @param array $item_id_mappings Item ID mappings.
330339
* @param array $sync_log The sync log
@@ -370,6 +379,7 @@ public function remote_get( $args = array() ) {
370379
// If post__in is empty, we can just stop right here
371380
restore_current_blog();
372381

382+
// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
373383
return apply_filters(
374384
'dt_remote_get',
375385
[
@@ -407,6 +417,7 @@ public function remote_get( $args = array() ) {
407417
$query_args['order'] = $args['order'];
408418
}
409419

420+
// Filter documented in includes/classes/ExternalConnections/WordPressExternalConnection.php
410421
$posts_query = new \WP_Query( apply_filters( 'dt_remote_get_query_args', $query_args, $args, $this ) );
411422

412423
$posts = $posts_query->posts;
@@ -424,6 +435,7 @@ public function remote_get( $args = array() ) {
424435

425436
restore_current_blog();
426437

438+
// Filter documented in /includes/classes/ExternalConnections/WordPressExternalConnection.php.
427439
return apply_filters(
428440
'dt_remote_get',
429441
[
@@ -450,6 +462,7 @@ public function remote_get( $args = array() ) {
450462

451463
restore_current_blog();
452464

465+
// Filter documented in /includes/classes/ExternalConnections/WordPressExternalConnection.php.
453466
return apply_filters( 'dt_remote_get', $formatted_post, $args, $this );
454467
}
455468
}
@@ -647,15 +660,15 @@ public static function get_available_authorized_sites( $context = null ) {
647660
}
648661

649662
/**
650-
* Allow plugins to override the default {@see \Distributor\InternalConnections\NetworkSiteConnection::get_available_authorized_sites()} function.
663+
* Enable plugins to filter the authorized sites, before they are retrieved.
651664
*
652665
* @since 1.2
653666
* @since 1.3.7 Added the `$context` parameter.
667+
* @hook dt_pre_get_authorized_sites
668+
*
669+
* @see \Distributor\InternalConnections\NetworkSiteConnection::get_available_authorized_sites()
654670
*
655-
* @param array $authorized_sites {
656-
* @type array {
657-
* 'site' => $site, // WP_Site object.
658-
* 'post_types' => $array, // List of post type objects the user can edit.
671+
* @param array $authorized_sites Array of WP_Site object and post type objects the user can edit.
659672
* }
660673
* @param string $context The context of the authorization.
661674
*/
@@ -671,11 +684,9 @@ public static function get_available_authorized_sites( $context = null ) {
671684
*
672685
* @since 1.2
673686
* @since 1.3.7 Added the `$context` parameter.
687+
* @hook dt_authorized_sites
674688
*
675-
* @param array $authorized_sites {
676-
* @type array {
677-
* 'site' => $site, // WP_Site object.
678-
* 'post_types' => $array, // List of post type objects the user can edit.
689+
* @param array $authorized_sites An array of WP_Site objects and the post type objects the user can edit.
679690
* }
680691
* @param string $context The context of the authorization.
681692
*/

‎includes/classes/PullListTable.php

+4
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ protected function bulk_actions( $which = '' ) {
136136
* This filter can currently only be used to remove bulk actions.
137137
*
138138
* @since 3.5.0
139+
* @hook bulk_actions-{$this->screen->id}
139140
*
140141
* @param array $actions An array of the available bulk actions.
141142
*/
@@ -243,8 +244,10 @@ public function column_date( $post ) {
243244
}
244245
echo '<br />';
245246
if ( 'excerpt' === $mode ) {
247+
// Core filter, documented in wp-admin/includes/class-wp-posts-list-table.php.
246248
echo esc_html( apply_filters( 'post_date_column_time', $t_time, $post, 'date', $mode ) );
247249
} else {
250+
// Core filter, documented in wp-admin/includes/class-wp-posts-list-table.php.
248251
echo '<abbr title="' . esc_attr( $t_time ) . '">' . esc_html( apply_filters( 'post_date_column_time', $h_time, $post, 'date', $mode ) ) . '</abbr>';
249252
}
250253
}
@@ -562,6 +565,7 @@ public function extra_tablenav( $which ) {
562565
* Action fired when extra table nav is generated.
563566
*
564567
* @since 1.0
568+
* @hook dt_pull_filters
565569
*/
566570
do_action( 'dt_pull_filters' );
567571
}

‎includes/external-connection-cpt.php

+2
Original file line numberDiff line numberDiff line change
@@ -573,6 +573,7 @@ function add_menu_item() {
573573
* Filter Distributor capabilities allowed to view external connections.
574574
*
575575
* @since 1.0.0
576+
* @hook dt_capabilities
576577
*
577578
* @param string manage_options The capability allowed to view external connections.
578579
*/
@@ -601,6 +602,7 @@ function add_submenu_item() {
601602
* Filter Distributor capabilities allowed to manage external connections.
602603
*
603604
* @since 1.0.0
605+
* @hook dt_external_capabilities
604606
*
605607
* @param string manage_options The capability allowed to manage external connections.
606608
*/

‎includes/pull-ui.php

+3
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ function action_admin_menu() {
132132
* Filter Distributor capabilities allowed to pull content.
133133
*
134134
* @since 1.0.0
135+
* @hook dt_pull_capabilities
135136
*
136137
* @param string manage_options The capability allowed to pull content.
137138
*/
@@ -189,6 +190,7 @@ function process_actions() {
189190
exit;
190191
}
191192

193+
// Filter documented above.
192194
if ( ! current_user_can( apply_filters( 'dt_pull_capabilities', 'manage_options' ) ) ) {
193195
wp_die(
194196
'<h1>' . esc_html__( 'Cheatin&#8217; uh?', 'distributor' ) . '</h1>' .
@@ -257,6 +259,7 @@ function( $remote_post_id ) use ( $post_type ) {
257259
exit;
258260
}
259261

262+
// Filter documented above.
260263
if ( ! current_user_can( apply_filters( 'dt_pull_capabilities', 'manage_options' ) ) ) {
261264
wp_die(
262265
'<h1>' . esc_html__( 'Cheatin&#8217; uh?', 'distributor' ) . '</h1>' .

0 commit comments

Comments
 (0)