Declarative way to mark commands and arguments deprecated #6342

Today, to deprecate a command or an argument, it's the command author's job to check for usage and emit a warning.

Example:

https://github.com/wp-cli/language-command/blob/7b60ecc34c28f278499e43a0be5dc9f3e3eea767/src/Core_Language_Command.php#L425-L447

What if we automatically checked the docblocks for deprecation annotations and handle this at the framework level?

It could work similar to the @skipglobalargcheck (for commands) and sensitive: true (for arguments) flags we recently added. See https://github.com/wp-cli/handbook/blob/2529c2f954c31df32cb95bdd2545fa3a1b05bd85/guides/commands-cookbook.md

The above example would become:

	/**
	 * Activates a given language.
	 *
	 * ## OPTIONS
	 *
	 * <language>
	 * : Language code to activate.
	 *
	 * ## EXAMPLES
	 *
	 *     # Activate the given language.
	 *     $ wp language core activate ja
	 *     Success: Language activated.
	 *
	 * @deprecated Use `wp site switch-language` instead
	 * @subcommand activate
	 * @throws WP_CLI\ExitException
	 *
	 * @param array{string} $args Positional arguments.
	 */
	public function activate( $args ) {
		list( $language_code ) = $args;

		$this->activate_language( $language_code );
	}

And for arguments:

 * [--password=<password>]
 * : Database password.
 * ---
 * deprecated: Use `--secret` instead
 * ---

At runtime, we would check for these and

1. Automatically add a sentence to the synopsis when using the help command
2. Print a warning before running the command