Merge pull request #602 from wp-cli/copilot/fix-multiline-argument-parsing

Author: swissspidy

bin/Handbook_Command.php

@@ -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 );
@@ -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 = '';

bin/handbook-manifest.json

@@ -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",
@@ -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",

internal-api/wp-cli-debug.md

@@ -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>
 
@@ -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.*

internal-api/wp-cli-do-hook.md

@@ -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>
 
 
@@ -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.*

internal-api/wp-cli-utils-esc-like.md

@@ -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>
 
 
@@ -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.*

internal-api/wp-cli-utils-http-request.md

@@ -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 />
@@ -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.*