minor symfony#19035 [Console] added explanation of messages usage in a progress bar (fabpot)

This PR was merged into the 2.7 branch.

Discussion
----------

[Console] added explanation of messages usage in a progress bar

| Q             | A
| ------------- | ---
| Branch?       | 2.7
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | symfony#19031
| License       | MIT
| Doc PR        | symfony/symfony-docs#6544

The intent of progress bar messages is currently wrongly documented. This PR updates the phpdoc to hopefully better describe the usage of such messages.

So, basically, messages are a way to add dynamic information in the progress bar; information that cannot be computed by the progress bar (like for all other placeholders).

Commits
-------

d92f3ea [Console] added explanation of messages usage in a progress bar

Author: fabpot

src/Symfony/Component/Console/Helper/ProgressBar.php

@@ -41,7 +41,7 @@ class ProgressBar
     private $stepWidth;
     private $percent = 0.0;
     private $formatLineCount;
-    private $messages;
+    private $messages = array();
     private $overwrite = true;
 
     private static $formatters;
@@ -139,6 +139,16 @@ public static function getFormatDefinition($name)
         return isset(self::$formats[$name]) ? self::$formats[$name] : null;
     }
 
+    /**
+     * Associates a text with a named placeholder.
+     *
+     * The text is displayed when the progress bar is rendered but only
+     * when the corresponding placeholder is part of the custom format line
+     * (by wrapping the name with %).
+     *
+     * @param string $message The text to associate with the placeholder
+     * @param string $name    The name of the placeholder
+     */
     public function setMessage($message, $name = 'message')
     {
         $this->messages[$name] = $message;