Making a few changes to the existing description and adding docs for the Formatter Helper

Author: Sgoettschkes

components/console/helpers/dialoghelper.rst

@@ -4,9 +4,8 @@
 Dialog Helper
 =============
 
-The Dialog Helper provides functions to ask the user for more information.
-
-The DialogHelper is included in the default helper set, which you can get
+The Dialog Helper provides functions to ask the user for more information. 
+It is included in the default helper set, which you can get
 by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
 
     $dialog = $this->getHelperSet()->get('dialog');
@@ -30,16 +29,16 @@ the following to your command::
         return;
     }
 
-In this case, the user will be asked "Continue with this action", and unless
-they answer with ``y``, the task will stop running. The third argument to
-``askConfirmation`` is the default value to return if the user doesn't enter
-any input.
+In this case, the user will be asked "Continue with this action", and will return
+``true`` if the user answers with ``y`` or false in any other case. The third 
+argument to ``askConfirmation`` is the default value to return if the user doesn't 
+enter any input.
 
 Asking the User for information
 -------------------------------
 
 You can also ask question with more than a simple yes/no answer. For instance,
-you want to know a bundle name, you can add this to your command::
+if you want to know a bundle name, you can add this to your command::
 
     // ...
     $bundle = $dialog->ask(
@@ -49,8 +48,8 @@ you want to know a bundle name, you can add this to your command::
     );
 
 The user will be asked "Please enter the name of the bundle". They can type
-some name or if they leave it empty the default value (``AcmeDemoBundle`` here)
-is used. This value will be returned.
+some name which will be returned by the ``ask`` method. If they leave it empty
+the default value (``AcmeDemoBundle`` here) is returned.
 
 Validating the answer
 ---------------------
@@ -87,10 +86,12 @@ This methods has 2 new arguments, the full signature is::
     )
 
 The ``$validator`` is a callback which handles the validation. It should
-throw an exception if there is something wrong. The exception message displayed
+throw an exception if there is something wrong. The exception message is displayed
 in the console, so it is a good practice to put some usefull information 
 in it.
 
 You can set the max number of times to ask in the ``$attempts`` argument.
 If we reach this max number it will use the default value, which is given
-in the last argument. This is ``false`` by default, which means it is infinite.
+in the last argument. Using ``false`` means the amount of attempts is infinite.
+The user will be asked as long as he provides an invalid answer and will only
+be able to proceed if his input is valid.

components/console/helpers/formatterhelper.rst

@@ -8,18 +8,42 @@ The Formatter helpers provides functions to format the output with colors.
 You can do more advanced things with this helper than the things in
 :ref:`components-console-coloring`.
 
-The FormatterHelper is included in the default helper set, which you can
+The Formatter Helper is included in the default helper set, which you can
 get by calling
 :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
 
     $formatter = $this->getHelperSet()->get('formatter');
 
-The methods return a string with the data for the console, you should decide
-what you are going to do with that data. In most cases you want to write
+The methods return a string which in most cases you want to write
 that data to the console with
 :method:`Symfony\\Component\\Console\\Output\\Output::writeln`.
 
 Print messages in a section
 ---------------------------
 
-Assume you want to print
+Symfony uses a defined style when printing to the command line.
+It prints the section in color and with brackets around and the
+actual message behind this section indication.
+
+To reproduce this style, you can use the `` formatSection`` method like this::
+
+    $formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
+    $output->writeln($formattedLine);
+    
+Print messages in a block
+-------------------------
+
+Sometimes you want to be able to print a whole block of text with a background
+color. Symfony uses this when printing error messages.
+
+If you print your error message on more than one line manually, you will 
+notice that the background is only as long as each individual line. You
+can use the `formatBlock` method to create a real block output::
+
+    $errorMessages = array('Error!', 'Something went wrong');
+    $formattedBlock = $formatter->formatBlock($errorMessages, 'error');
+    
+As you can see, passing an array of messages to the `formatBlock` method creates
+the desired output. If you pass `true` as third parameter, the block will be 
+formatted with more padding (one blank line above and below the messages and 2 
+spaces on the left and right).

components/console/helpers/index.rst

@@ -9,7 +9,6 @@ Console Helpers
 
     dialoghelper
 
-
 The Console Components comes with some usefull helpers. These helpers contain
 function to ease some common tasks.