Update handbook after v2.12.0 release

bin/command.php

@@ -408,6 +408,7 @@ public function gen_hb_manifest() {
 				'parent'          => null,
 			];
 		}
+
 		// Internal API pages.
 		foreach ( glob( WP_CLI_HANDBOOK_PATH . '/internal-api/*.md' ) as $file ) {
 			$slug     = basename( $file, '.md' );
@@ -426,6 +427,26 @@ public function gen_hb_manifest() {
 				'parent'          => 'internal-api',
 			];
 		}
+
+		// Behat steps pages.
+		foreach ( glob( WP_CLI_HANDBOOK_PATH . '/behat-steps/*.md' ) as $file ) {
+			$slug     = basename( $file, '.md' );
+			$title    = '';
+			$contents = file_get_contents( $file );
+			if ( preg_match( '/^#\s(.+)/', $contents, $matches ) ) {
+				$title = $matches[1];
+			}
+			$manifest[ $slug ] = [
+				'title'           => $title,
+				'slug'            => $slug,
+				'markdown_source' => sprintf(
+					'https://github.com/wp-cli/handbook/blob/main/behat-steps/%s.md',
+					$slug
+				),
+				'parent'          => 'ibehat-stepsapi',
+			];
+		}
+
 		file_put_contents( WP_CLI_HANDBOOK_PATH . '/bin/handbook-manifest.json', json_encode( $manifest, JSON_PRETTY_PRINT ) );
 		WP_CLI::success( 'Generated bin/handbook-manifest.json' );
 	}

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

@@ -11,7 +11,7 @@ Schedule a callback to be executed at a certain point.
 <div>
 <strong>$when</strong> (string) Identifier for the hook.<br />
 <strong>$callback</strong> (mixed) Callback to execute when hook is called.<br />
-<strong>@return</strong> (null) <br />
+<strong>@return</strong> (void) <br />
 </div>
 
 

internal-api/wp-cli-debug.md

@@ -11,7 +11,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>@return</strong> (null) <br />
+<strong>@return</strong> (void) <br />
 </div>
 
 

internal-api/wp-cli-line.md

@@ -10,7 +10,7 @@ Display informational message without prefix, and ignore `--quiet`.
 
 <div>
 <strong>$message</strong> (string) Message to display to the end user.<br />
-<strong>@return</strong> (null) <br />
+<strong>@return</strong> (void) <br />
 </div>
 
 

internal-api/wp-cli-runcommand.md

@@ -10,7 +10,7 @@ Run a WP-CLI command.
 
 <div>
 <strong>$command</strong> (string) WP-CLI command to run, including arguments.<br />
-<strong>$options</strong> (array) Configuration options for command execution.<br />
+<strong>$options</strong> (array) {<br />    Configuration options for command execution.<br />    @type bool        $launch     Launches a new process (true) or reuses the existing process (false). Default: true.<br />    @type bool        $exit_error Halts the script on error. Default: true.<br />    @type bool|string $return     Returns output as an object when set to 'all' (string), return just the 'stdout', 'stderr', or 'return_code' (string) of command, or print directly to stdout/stderr (false). Default: false.<br />    @type bool|string $parse      Parse returned output as 'json' (string); otherwise, output is unchanged (false). Default: false.<br />@param array $command_args Contains additional command line arguments for the command. Each element represents a single argument. Default: empty array.<br />}<br />
 <strong>@return</strong> (mixed) <br />
 </div>
 

internal-api/wp-cli-success.md

@@ -10,15 +10,15 @@ Display success message prefixed with "Success: ".
 
 <div>
 <strong>$message</strong> (string) Message to write to STDOUT.<br />
-<strong>@return</strong> (null) <br />
+<strong>@return</strong> (void) <br />
 </div>
 
 
 ***
 
 ## Notes
 
-Success message is written to STDOUT.
+Success message is written to STDOUT, or discarded when `--quiet` flag is supplied.
 
 Typically recommended to inform user of successful script conclusion.
 

internal-api/wp-cli-utils-format-items.md

@@ -10,8 +10,8 @@ Render a collection of items as an ASCII table, JSON, CSV, YAML, list of ids, or
 
 <div>
 <strong>$format</strong> (string) Format to use: 'table', 'json', 'csv', 'yaml', 'ids', 'count'.<br />
-<strong>$items</strong> (array) An array of items to output.<br />
-<strong>$fields</strong> (array|string) Named fields for each item of data. Can be array or comma-separated list.<br />
+<strong>$items</strong> (array&lt;mixed&gt;) An array of items to output.<br />
+<strong>$fields</strong> (array&lt;string&gt;|string) Named fields for each item of data. Can be array or comma-separated list.<br />
 </div>
 
 

internal-api/wp-cli-utils-get-flag-value.md

@@ -9,7 +9,7 @@ Return the flag value or, if it's not set, the $default value.
     WP_CLI\Utils\get_flag_value( $assoc_args, $flag, $default = null )
 
 <div>
-<strong>$assoc_args</strong> (array) Arguments array.<br />
+<strong>$assoc_args</strong> (array&lt;string,string|bool&gt;) Arguments array.<br />
 <strong>$flag</strong> (string) Flag to get the value.<br />
 <strong>$default</strong> (mixed) Default value for the flag. Default: NULL.<br />
 <strong>@return</strong> (mixed) <br />

internal-api/wp-cli-utils-parse-ssh-url.md

@@ -9,6 +9,8 @@ Parse a SSH url for its host, port, and path.
     WP_CLI\Utils\parse_ssh_url( $url, $component = -1 )
 
 <div>
+<strong>$url</strong> (string) <br />
+<strong>$component</strong> (int) <br />
 <strong>@return</strong> (mixed) <br />
 </div>
 

internal-api/wp-cli-utils-parse-str-to-argv.md

@@ -10,7 +10,7 @@ Parse a string of command line arguments into an $argv-esqe variable.
 
 <div>
 <strong>$arguments</strong> (string) <br />
-<strong>@return</strong> (array) <br />
+<strong>@return</strong> (array&lt;string&gt;) <br />
 </div>
 
 

internal-api/wp-cli-utils-proc-open-compat.md

@@ -10,11 +10,11 @@ Windows compatible `proc_open()`. Works around bug in PHP, and also deals with *
 
 <div>
 <strong>$cmd</strong> (string) Command to execute.<br />
-<strong>$descriptorspec</strong> (array) Indexed array of descriptor numbers and their values.<br />
-<strong>&amp;$pipes</strong> (array) Indexed array of file pointers that correspond to PHP's end of any pipes that are created.<br />
+<strong>string&gt;</strong> (array&lt;int,) $descriptorspec Indexed array of descriptor numbers and their values.<br />
+<strong>string&gt;</strong> (array&lt;int,) &$pipes         Indexed array of file pointers that correspond to PHP's end of any pipes that are created.<br />
 <strong>$cwd</strong> (string) Initial working directory for the command.<br />
-<strong>$env</strong> (array) Array of environment variables.<br />
-<strong>$other_options</strong> (array) Array of additional options (Windows only).<br />
+<strong>string&gt;</strong> (array&lt;string,) $env            Array of environment variables.<br />
+<strong>$other_options</strong> (array&lt;string&gt;) Array of additional options (Windows only).<br />
 <strong>@return</strong> (resource) stripped of any environment variable settings.<br />
 </div>
 

internal-api/wp-cli-utils-report-batch-operation-results.md

@@ -15,6 +15,7 @@ Report the results of the same operation against multiple resources.
 <strong>$successes</strong> (integer) Number of successful operations.<br />
 <strong>$failures</strong> (integer) Number of failures.<br />
 <strong>$skips</strong> (null|integer) Optional. Number of skipped operations. Default null (don't show skips).<br />
+<strong>@return</strong> (void) <br />
 </div>
 
 

internal-api/wp-cli-utils-write-csv.md

@@ -10,8 +10,8 @@ Write data as CSV to a given file.
 
 <div>
 <strong>$fd</strong> (resource) File descriptor.<br />
-<strong>$rows</strong> (array) Array of rows to output.<br />
-<strong>$headers</strong> (array) List of CSV columns (optional).<br />
+<strong>$rows</strong> (array&lt;string&gt;) Array of rows to output.<br />
+<strong>$headers</strong> (array&lt;string&gt;) List of CSV columns (optional).<br />
 </div>
 
 

internal-api/wp-cli-warning.md

@@ -10,15 +10,15 @@ Display warning message prefixed with "Warning: ".
 
 <div>
 <strong>$message</strong> (string|WP_Error|Exception|Throwable) Message to write to STDERR.<br />
-<strong>@return</strong> (null) <br />
+<strong>@return</strong> (void) <br />
 </div>
 
 
 ***
 
 ## Notes
 
-Warning message is written to STDERR.
+Warning message is written to STDERR, or discarded when `--quiet` flag is supplied.
 
 Use instead of `WP_CLI::debug()` when script execution should be permitted
 to continue.