Currently there are two methods for describing new commands.

• specifically formatted phpdocs for the command.
• including short_desc and specifically structured synopsis array items in the third argument when registering the command

However, if one chooses to use the second option above (which has good use case when dynamically registering commands), there's no current way to provide "Examples" of usage.

The current structure of this third argument is found here:

* @param array $args {
	 *      Optional An associative array with additional registration parameters.
	 *      'before_invoke' => callback to execute before invoking the command,
	 *      'after_invoke' => callback to execute after invoking the command,
	 *      'shortdesc' => short description (80 char or less) for the command,
	 *      'synopsis' => the synopsis for the command (string or array),
	 *      'when' => execute callback on a named WP-CLI hook (e.g. before_wp_load),
	 * }

I'm proposing adding an additional key to that index examples.

The format for this additional argument would be structured array of arrays where each array represents an example.

array(
    'examples' => array(
        array(
            'short_description' => 'Command example description',
            'command' => 'wp command example',
            'result' => 'Success: The example subcommand has successfully executed for command.'
        )
    )
);

//Results in this in the output
// # Command example description
// $ wp command example
// Success: The example subcommand has successfully executed for command.

Structured array's allow for ensuring output follows the current documentation standards outlined here.