Skip to content

Fix docblock parser to handle multiline descriptions for all tags #602

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
swissspidy merged 7 commits into from
Dec 17, 2025
Merged

Fix docblock parser to handle multiline descriptions for all tags #602

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8c105ce
Initial plan
Copilot Dec 8, 2025
089342c
Fix parsing of multiline argument descriptions in docblocks
Copilot Dec 8, 2025
5fde237
Add empty string check before accessing array index
Copilot Dec 8, 2025
cbd23f1
Merge branch 'main' into copilot/fix-multiline-argument-parsing
swissspidy Dec 17, 2025
4f9bc64
Regenerate docs
swissspidy Dec 17, 2025
9ec518a
Handle multiline descriptions for @return and other tags
Copilot Dec 17, 2025
aac59dc
Regenerate
swissspidy Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions bin/Handbook_Command.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -791,13 +791,10 @@ private static function parse_docblock( $docblock ) {
if ( preg_match( '/^(?=\s+?\*[^\/])(.+)/', $line, $matches ) ) {
$info = trim( $matches[1] );
$info = preg_replace( '/^(\*\s+?)/', '', $info );
if ( $in_param ) {
if ( $in_param && ! empty( $info ) && '@' !== $info[0] ) {
list( $param_name, $key ) = $in_param;
$ret['parameters'][ $param_name ][ $key ][2] .= PHP_EOL . $info;
if ( '}' === substr( $info, -1 ) ) {
$in_param = false;
}
} elseif ( '@' !== $info[0] ) {
} elseif ( ! empty( $info ) && '@' !== $info[0] ) {
$ret['description'] .= PHP_EOL . "{$extra_line}{$info}";
} else {
preg_match( '/@(\w+)/', $info, $matches );
Expand All @@ -815,9 +812,11 @@ private static function parse_docblock( $docblock ) {
end( $ret['parameters'][ $param_name ] );
$key = key( $ret['parameters'][ $param_name ] );
reset( $ret['parameters'][ $param_name ] );
if ( ! empty( $ret['parameters'][ $param_name ][ $key ][2] )
&& '{' === substr( $ret['parameters'][ $param_name ][ $key ][2], -1 ) ) {
// Always set $in_param for tags that can have multiline descriptions
if ( ! empty( $ret['parameters'][ $param_name ][ $key ][2] ) ) {
$in_param = [ $param_name, $key ];
} else {
$in_param = false;
}
}
$extra_line = '';
Expand Down
8 changes: 4 additions & 4 deletions bin/handbook-manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@
"behat-steps": {
"title": "Behat Steps",
"slug": "behat-steps",
"markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/behat-steps.md",
"parent": null
"markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/references\/behat-steps.md",
"parent": "references"
},
"bug-reports": {
"title": "Bug Reports",
Expand Down Expand Up @@ -368,8 +368,8 @@
"internal-api": {
"title": "Internal API",
"slug": "internal-api",
"markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/internal-api.md",
"parent": null
"markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/references\/internal-api.md",
"parent": "references"
},
"philosophy": {
"title": "Philosophy",
Expand Down
3 changes: 1 addition & 2 deletions internal-api/wp-cli-debug.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Display debug message prefixed with "Debug: " when `--debug` is used.

<div>
<strong>$message</strong> (string|WP_Error|Exception|Throwable) Message to write to STDERR.<br />
<strong>$group</strong> (string|bool) Organize debug message to a specific group.<br />
<strong>$group</strong> (string|bool) Organize debug message to a specific group.<br />Use `false` to not group the message.<br />
<strong>@return</strong> (void) <br />
</div>

Expand All @@ -37,7 +37,6 @@ private static function set_wp_root( $path ) {
# [...]
# Debug: ABSPATH defined: /srv/www/wordpress-develop.dev/src/ (0.225s)
```
Use `false` to not group the message.


*Internal API documentation is generated from the WP-CLI codebase on every release. To suggest improvements, please submit a pull request.*
Expand Down
6 changes: 2 additions & 4 deletions internal-api/wp-cli-do-hook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ Execute callbacks registered to a given hook.

<div>
<strong>$when</strong> (string) Identifier for the hook.<br />
<strong>...$args</strong> (mixed) Optional. Arguments that will be passed onto the<br />
<strong>@return</strong> (null|mixed) the first optional argument if optional<br />
<strong>...$args</strong> (mixed) Optional. Arguments that will be passed onto the<br /> callback provided by `WP_CLI::add_hook()`.<br />
<strong>@return</strong> (null|mixed) the first optional argument if optional&lt;br /&gt; arguments were passed, otherwise returns null.<br />
</div>


Expand All @@ -21,8 +21,6 @@ Execute callbacks registered to a given hook.

See `WP_CLI::add_hook()` for details on WP-CLI's internal hook system.
Commands can provide and call their own hooks.
callback provided by `WP_CLI::add_hook()`.
arguments were passed, otherwise returns null.


*Internal API documentation is generated from the WP-CLI codebase on every release. To suggest improvements, please submit a pull request.*
Expand Down
6 changes: 2 additions & 4 deletions internal-api/wp-cli-utils-esc-like.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ First half of escaping for LIKE special characters % and _ before preparing for
WP_CLI\Utils\esc_like( $text )

<div>
<strong>$text</strong> (string) The raw text to be escaped. The input typed by the user should have no<br />
<strong>@return</strong> (string) in the form of a LIKE phrase. The output is not SQL safe. Call $wpdb::prepare()<br />
<strong>$text</strong> (string) The raw text to be escaped. The input typed by the user should have no<br /> extra or deleted slashes.<br />
<strong>@return</strong> (string) in the form of a LIKE phrase. The output is not SQL safe. Call $wpdb::prepare()&lt;br /&gt; or real_escape next.<br />
</div>


Expand All @@ -21,8 +21,6 @@ First half of escaping for LIKE special characters % and _ before preparing for
Use this only before wpdb::prepare() or esc_sql(). Reversing the order is very bad for security.

Copied from core "wp-includes/wp-db.php". Avoids dependency on WP 4.4 wpdb.
extra or deleted slashes.
or real_escape next.


*Internal API documentation is generated from the WP-CLI codebase on every release. To suggest improvements, please submit a pull request.*
Expand Down
3 changes: 1 addition & 2 deletions internal-api/wp-cli-utils-http-request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Make a HTTP request to a remote URL.
<div>
<strong>$method</strong> (string) HTTP method (GET, POST, DELETE, etc.).<br />
<strong>$url</strong> (string) URL to make the HTTP request to.<br />
<strong>$data</strong> (array|null) Data to send either as a query string for GET/HEAD requests,<br />
<strong>$data</strong> (array|null) Data to send either as a query string for GET/HEAD requests,<br /> or in the body for POST requests.<br />
<strong>$headers</strong> (array) Add specific headers to the request.<br />
<strong>$options</strong> (array) {<br /> Optional. An associative array of additional request options.<br /> @type bool $halt_on_error Whether or not command execution should be halted on error. Default: true<br /> @type bool|string $verify A boolean to use enable/disable SSL verification<br /> or string absolute path to CA cert to use.<br /> Defaults to detected CA cert bundled with the Requests library.<br /> @type bool $insecure Whether to retry automatically without certificate validation.<br />}<br />
<strong>@return</strong> (\Requests_Response|Response) <br />
Expand All @@ -32,7 +32,6 @@ if ( 20 != substr( $md5_response->status_code, 0, 2 ) ) {
WP_CLI::error( "Couldn't access md5 hash for release (HTTP code {$response->status_code})" );
}
```
or in the body for POST requests.


*Internal API documentation is generated from the WP-CLI codebase on every release. To suggest improvements, please submit a pull request.*
Expand Down