minor #14662 added supported format in commands supporting --format (fabpot)

This PR was merged into the 2.7 branch.

Discussion
----------

added supported format in commands supporting --format

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

replaces #14084

Commits
-------

ea874b6 added supported format in commands supporting --format
c4bf217 deprecated the --xml option for commands

src/Symfony/Bridge/Twig/Command/DebugCommand.php

@@ -18,7 +18,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
 /**
- * Lists twig functions, filters, globals and tests present in the current project
+ * Lists twig functions, filters, globals and tests present in the current project.
  *
  * @author Jordi Boggiano <j.boggiano@seld.be>
  */
@@ -35,7 +35,7 @@ class DebugCommand extends Command
     }
 
     /**
-     * Sets the twig environment
+     * Sets the twig environment.
      *
      * @param \Twig_Environment $twig
      */
@@ -57,7 +57,7 @@ class DebugCommand extends Command
         $this
             ->setDefinition(array(
                 new InputArgument('filter', InputArgument::OPTIONAL, 'Show details for all entries matching this filter'),
-                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'Output format: text or json', 'text'),
+                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (text or json)', 'text'),
             ))
             ->setDescription('Shows a list of twig functions, filters, globals and tests')
             ->setHelp(<<<EOF

src/Symfony/Bundle/FrameworkBundle/Command/ConfigDumpReferenceCommand.php

@@ -37,7 +37,7 @@ class ConfigDumpReferenceCommand extends AbstractConfigCommand
             ->setName('config:dump-reference')
             ->setDefinition(array(
                 new InputArgument('name', InputArgument::OPTIONAL, 'The Bundle name or the extension alias'),
-                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The format, either yaml or xml', 'yaml'),
+                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (yaml or xml)', 'yaml'),
             ))
             ->setDescription('Dumps the default configuration for an extension')
             ->setHelp(<<<EOF

src/Symfony/Bundle/FrameworkBundle/Command/ContainerDebugCommand.php

@@ -50,7 +50,7 @@ class ContainerDebugCommand extends ContainerAwareCommand
                 new InputOption('tags', null, InputOption::VALUE_NONE, 'Displays tagged services for an application'),
                 new InputOption('parameter', null, InputOption::VALUE_REQUIRED, 'Displays a specific parameter for an application'),
                 new InputOption('parameters', null, InputOption::VALUE_NONE, 'Displays parameters for an application'),
-                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'To output description in other formats', 'txt'),
+                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (txt, xml, json, or md)', 'txt'),
                 new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw description'),
             ))
             ->setDescription('Displays current services for an application')

src/Symfony/Bundle/FrameworkBundle/Command/EventDispatcherDebugCommand.php

@@ -19,7 +19,7 @@ use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 
 /**
- * A console command for retrieving information about event dispatcher
+ * A console command for retrieving information about event dispatcher.
  *
  * @author Matthieu Auger <mail@matthieuauger.com>
  */
@@ -34,7 +34,7 @@ class EventDispatcherDebugCommand extends ContainerAwareCommand
             ->setName('debug:event-dispatcher')
             ->setDefinition(array(
                 new InputArgument('event', InputArgument::OPTIONAL, 'An event name'),
-                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'To output description in other formats', 'txt'),
+                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format  (txt, xml, json, or md)', 'txt'),
                 new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw description'),
             ))
             ->setDescription('Displays configured listeners for an application')
@@ -87,7 +87,7 @@ EOF
     }
 
     /**
-     * Loads the Event Dispatcher from the container
+     * Loads the Event Dispatcher from the container.
      *
      * @return EventDispatcherInterface
      */

src/Symfony/Bundle/FrameworkBundle/Command/RouterDebugCommand.php

@@ -56,7 +56,7 @@ class RouterDebugCommand extends ContainerAwareCommand
             ->setDefinition(array(
                 new InputArgument('name', InputArgument::OPTIONAL, 'A route name'),
                 new InputOption('show-controllers', null, InputOption::VALUE_NONE, 'Show assigned controllers in overview'),
-                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'To output route(s) in other formats', 'txt'),
+                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (txt, xml, json, or md)', 'txt'),
                 new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw route(s)'),
             ))
             ->setDescription('Displays current routes for an application')

src/Symfony/Component/Console/Command/HelpCommand.php

@@ -38,7 +38,7 @@ class HelpCommand extends Command
             ->setDefinition(array(
                 new InputArgument('command_name', InputArgument::OPTIONAL, 'The command name', 'help'),
                 new InputOption('xml', null, InputOption::VALUE_NONE, 'To output help as XML'),
-                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'To output help in other formats', 'txt'),
+                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (txt, xml, json, or md)', 'txt'),
                 new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw command help'),
             ))
             ->setDescription('Displays help for a command')
@@ -77,6 +77,8 @@ EOF
         }
 
         if ($input->getOption('xml')) {
+            trigger_error('The --xml option was deprecated in version 2.7 and will be removed in version 3.0. Use the --format option instead.', E_USER_DEPRECATED);
+
             $input->setOption('format', 'xml');
         }
 

src/Symfony/Component/Console/Command/ListCommand.php

@@ -69,6 +69,8 @@ EOF
     protected function execute(InputInterface $input, OutputInterface $output)
     {
         if ($input->getOption('xml')) {
+            trigger_error('The --xml option was deprecated in version 2.7 and will be removed in version 3.0. Use the --format option instead.', E_USER_DEPRECATED);
+
             $input->setOption('format', 'xml');
         }
 
@@ -89,7 +91,7 @@ EOF
             new InputArgument('namespace', InputArgument::OPTIONAL, 'The namespace name'),
             new InputOption('xml', null, InputOption::VALUE_NONE, 'To output list as XML'),
             new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw command list'),
-            new InputOption('format', null, InputOption::VALUE_REQUIRED, 'To output list in other formats', 'txt'),
+            new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (txt, xml, json, or md)', 'txt'),
         ));
     }
 }

src/Symfony/Component/Console/Tests/Fixtures/application_1.json

@@ -1 +1 @@
-{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}}],"namespaces":[{"id":"_global","commands":["help","list"]}]}
+{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"The output format (txt, xml, json, or md)","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"The output format (txt, xml, json, or md)","default":"txt"}}}}],"namespaces":[{"id":"_global","commands":["help","list"]}]}

src/Symfony/Component/Console/Tests/Fixtures/application_1.md

@@ -51,7 +51,7 @@ To display the list of available commands, please use the <info>list</info> comm
 * Accept value: yes
 * Is value required: yes
 * Is multiple: no
-* Description: To output help in other formats
+* Description: The output format (txt, xml, json, or md)
 * Default: `'txt'`
 
 **raw:**
@@ -197,5 +197,5 @@ It's also possible to get raw list of commands (useful for embedding command run
 * Accept value: yes
 * Is value required: yes
 * Is multiple: no
-* Description: To output list in other formats
+* Description: The output format (txt, xml, json, or md)
 * Default: `'txt'`

src/Symfony/Component/Console/Tests/Fixtures/application_1.xml

@@ -28,7 +28,7 @@
           <description>To output help as XML</description>
         </option>
         <option name="--format" shortcut="" accept_value="1" is_value_required="1" is_multiple="0">
-          <description>To output help in other formats</description>
+          <description>The output format (txt, xml, json, or md)</description>
           <defaults>
             <default>txt</default>
           </defaults>
@@ -93,7 +93,7 @@
           <description>To output raw command list</description>
         </option>
         <option name="--format" shortcut="" accept_value="1" is_value_required="1" is_multiple="0">
-          <description>To output list in other formats</description>
+          <description>The output format (txt, xml, json, or md)</description>
           <defaults>
             <default>txt</default>
           </defaults>

src/Symfony/Component/Console/Tests/Fixtures/application_2.md

@@ -58,7 +58,7 @@ To display the list of available commands, please use the <info>list</info> comm
 * Accept value: yes
 * Is value required: yes
 * Is multiple: no
-* Description: To output help in other formats
+* Description: The output format (txt, xml, json, or md)
 * Default: `'txt'`
 
 **raw:**
@@ -204,7 +204,7 @@ It's also possible to get raw list of commands (useful for embedding command run
 * Accept value: yes
 * Is value required: yes
 * Is multiple: no
-* Description: To output list in other formats
+* Description: The output format (txt, xml, json, or md)
 * Default: `'txt'`
 
 descriptor:command1

src/Symfony/Component/Console/Tests/Fixtures/application_2.xml

@@ -28,7 +28,7 @@
           <description>To output help as XML</description>
         </option>
         <option name="--format" shortcut="" accept_value="1" is_value_required="1" is_multiple="0">
-          <description>To output help in other formats</description>
+          <description>The output format (txt, xml, json, or md)</description>
           <defaults>
             <default>txt</default>
           </defaults>
@@ -93,7 +93,7 @@
           <description>To output raw command list</description>
         </option>
         <option name="--format" shortcut="" accept_value="1" is_value_required="1" is_multiple="0">
-          <description>To output list in other formats</description>
+          <description>The output format (txt, xml, json, or md)</description>
           <defaults>
             <default>txt</default>
           </defaults>

src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt

@@ -28,7 +28,7 @@
       <description>To output help as XML</description>
     </option>
     <option name="--format" shortcut="" accept_value="1" is_value_required="1" is_multiple="0">
-      <description>To output help in other formats</description>
+      <description>The output format (txt, xml, json, or md)</description>
       <defaults>
         <default>txt</default>
       </defaults>
@@ -93,7 +93,7 @@
       <description>To output raw command list</description>
     </option>
     <option name="--format" shortcut="" accept_value="1" is_value_required="1" is_multiple="0">
-      <description>To output list in other formats</description>
+      <description>The output format (txt, xml, json, or md)</description>
       <defaults>
         <default>txt</default>
       </defaults>

src/Symfony/Component/Console/Tests/Fixtures/application_run2.txt

@@ -7,7 +7,7 @@ Arguments:
 
 Options:
       --xml             To output help as XML
-      --format=FORMAT   To output help in other formats [default: "txt"]
+      --format=FORMAT   The output format (txt, xml, json, or md) [default: "txt"]
       --raw             To output raw command help
   -h, --help            Display this help message
   -q, --quiet           Do not output any message

src/Symfony/Component/Console/Tests/Fixtures/application_run3.txt

@@ -7,7 +7,7 @@ Arguments:
 Options:
       --xml            To output list as XML
       --raw            To output raw command list
-      --format=FORMAT  To output list in other formats [default: "txt"]
+      --format=FORMAT  The output format (txt, xml, json, or md) [default: "txt"]
 
 Help:
  The list command lists all commands: