Clarify WP_CLI::runcommand()

Author: danielbachhuber

_posts/2016-11-29-version-1.0.0.md

@@ -6,12 +6,18 @@ title: Version 1.0.0 released
 
 Woohoo!
 
-*What does v1.0.0 mean?*
 
 
 ### Introducing `WP_CLI::runcommand()`
 
-`WP_CLI::runcommand()` is the best way to run WP-CLI commands from within your WP-CLI command.
+`WP_CLI::runcommand()` ([doc](/docs/internal-api/wp-cli-runcommand/)) is the new best way to run WP-CLI commands from within your WP-CLI command. It's as though `WP_CLI::run_command()` and `WP_CLI::launch_self()` grew up, married, and had a perfect child.
+
+With `WP_CLI::runcommand()`, you can:
+
+* Launch a new child process (default), or reuse the existing process.
+* Optionally prevent the process from exiting on error.
+* Return STDOUT generated by the command, or all command execution details (STDOUT, STDERR, return_code) as an object.
+* Optionally parse captured STDOUT as JSON.
 
 ### Breaking changes: Uses return code 1 when batch operation partially fails.
 
@@ -28,7 +34,9 @@ Affected commands include:
 * `wp term delete`
 * `wp widget (delete|deactivate|reset)`
 
-Use `WP_CLI\Utils\report_batch_operation_results()` in your custom WP-CLI commands to more easily support this behavior.
+Use `WP_CLI\Utils\report_batch_operation_results()` ([doc](/docs/internal-api/wp-cli-utils-report-batch-operation-results/)) in your custom WP-CLI commands to more easily support this behavior.
+
+See [this issue](https://github.com/wp-cli/wp-cli/issues/3577) for more background and rationale.
 
 Relevant pull requests include: [#3584](https://github.com/wp-cli/wp-cli/pull/3584), [#3583](https://github.com/wp-cli/wp-cli/pull/3583), [#3582](https://github.com/wp-cli/wp-cli/pull/3582), [#3585](https://github.com/wp-cli/wp-cli/pull/3585), [#3586](https://github.com/wp-cli/wp-cli/pull/3586), [#3588](https://github.com/wp-cli/wp-cli/pull/3588)