Merge branch '2.8' into 3.3

* 2.8:
  [2.8] Fix some docblocks
  Escape trailing \ in QuestionHelper autocompletion
  Add "doctrine/annotations" to top-level composer.json
  Remove inapplicable phpdoc comment
  nit: Fix phpdoc inconsistency and unreachable statement

Author: nicolas-grekas

composer.json

@@ -87,6 +87,7 @@
     },
     "require-dev": {
         "cache/integration-tests": "dev-master",
+        "doctrine/annotations": "~1.0",
         "doctrine/cache": "~1.6",
         "doctrine/data-fixtures": "1.0.*",
         "doctrine/dbal": "~2.4",

src/Symfony/Bundle/FrameworkBundle/Console/Descriptor/TextDescriptor.php

@@ -417,9 +417,6 @@ protected function describeCallable($callable, array $options = array())
         $this->writeText($this->formatCallable($callable), $options);
     }
 
-    /**
-     * @param array $array
-     */
     private function renderEventListenerTable(EventDispatcherInterface $eventDispatcher, $event, array $eventListeners, SymfonyStyle $io)
     {
         $tableHeaders = array('Order', 'Callable', 'Priority');

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

@@ -13,11 +13,12 @@
 
 use Symfony\Component\Console\Exception\InvalidArgumentException;
 use Symfony\Component\Console\Exception\RuntimeException;
+use Symfony\Component\Console\Formatter\OutputFormatter;
+use Symfony\Component\Console\Formatter\OutputFormatterStyle;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\StreamableInputInterface;
 use Symfony\Component\Console\Output\ConsoleOutputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
-use Symfony\Component\Console\Formatter\OutputFormatterStyle;
 use Symfony\Component\Console\Question\Question;
 use Symfony\Component\Console\Question\ChoiceQuestion;
 
@@ -324,7 +325,7 @@ private function autocomplete(OutputInterface $output, Question $question, $inpu
                 // Save cursor position
                 $output->write("\0337");
                 // Write highlighted text
-                $output->write('<hl>'.substr($matches[$ofs], $i).'</hl>');
+                $output->write('<hl>'.OutputFormatter::escapeTrailingBackslash(substr($matches[$ofs], $i)).'</hl>');
                 // Restore cursor position
                 $output->write("\0338");
             }

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

@@ -48,7 +48,7 @@ class Table
     /**
      * Number of columns cache.
      *
-     * @var array
+     * @var int
      */
     private $numberOfColumns;
 

src/Symfony/Component/Console/Tests/Helper/QuestionHelperTest.php

@@ -153,6 +153,46 @@ public function testAskWithAutocompleteWithNonSequentialKeys()
         $this->assertEquals('AsseticBundle', $dialog->ask($this->createStreamableInputInterfaceMock($inputStream), $this->createOutputInterface(), $question));
     }
 
+    public function testAutocompleteWithTrailingBackslash()
+    {
+        if (!$this->hasSttyAvailable()) {
+            $this->markTestSkipped('`stty` is required to test autocomplete functionality');
+        }
+
+        $inputStream = $this->getInputStream('E');
+
+        $dialog = new QuestionHelper();
+        $dialog->setInputStream($inputStream);
+        $helperSet = new HelperSet(array(new FormatterHelper()));
+        $dialog->setHelperSet($helperSet);
+
+        $question = new Question('');
+        $expectedCompletion = 'ExampleNamespace\\';
+        $question->setAutocompleterValues(array($expectedCompletion));
+
+        $output = $this->createOutputInterface();
+        $dialog->ask($this->createInputInterfaceMock(), $output, $question);
+
+        $outputStream = $output->getStream();
+        rewind($outputStream);
+        $actualOutput = stream_get_contents($outputStream);
+
+        // Shell control (esc) sequences are not so important: we only care that
+        // <hl> tag is interpreted correctly and replaced
+        $irrelevantEscSequences = array(
+            "\0337" => '', // Save cursor position
+            "\0338" => '', // Restore cursor position
+            "\033[K" => '', // Clear line from cursor till the end
+        );
+
+        $importantActualOutput = strtr($actualOutput, $irrelevantEscSequences);
+
+        // Remove colors (e.g. "\033[30m", "\033[31;41m")
+        $importantActualOutput = preg_replace('/\033\[\d+(;\d+)?m/', '', $importantActualOutput);
+
+        $this->assertEquals($expectedCompletion, $importantActualOutput);
+    }
+
     public function testAskHiddenResponse()
     {
         if ('\\' === DIRECTORY_SEPARATOR) {

src/Symfony/Component/Routing/RouteCollectionBuilder.php

@@ -38,9 +38,6 @@ class RouteCollectionBuilder
     private $methods;
     private $resources = array();
 
-    /**
-     * @param LoaderInterface $loader
-     */
     public function __construct(LoaderInterface $loader = null)
     {
         $this->loader = $loader;

src/Symfony/Component/Security/Guard/GuardAuthenticatorHandler.php

@@ -44,9 +44,6 @@ public function __construct(TokenStorageInterface $tokenStorage, EventDispatcher
 
     /**
      * Authenticates the given token in the system.
-     *
-     * @param TokenInterface $token
-     * @param Request        $request
      */
     public function authenticateWithToken(TokenInterface $token, Request $request)
     {

src/Symfony/Component/Serializer/Tests/Encoder/ChainEncoderTest.php

@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Serializer\Encoder\ChainEncoder;
+use Symfony\Component\Serializer\Encoder\EncoderInterface;
 use Symfony\Component\Serializer\Encoder\NormalizationAwareInterface;
 
 class ChainEncoderTest extends TestCase
@@ -123,10 +124,14 @@ class ChainNormalizationAwareEncoder extends ChainEncoder implements Normalizati
 {
 }
 
-class NormalizationAwareEncoder implements NormalizationAwareInterface
+class NormalizationAwareEncoder implements EncoderInterface, NormalizationAwareInterface
 {
     public function supportsEncoding($format)
     {
         return true;
     }
+
+    public function encode($data, $format, array $context = array())
+    {
+    }
 }

src/Symfony/Component/Translation/PluralizationRules.php

@@ -71,7 +71,6 @@ public static function get($number, $locale)
             case 'vi':
             case 'zh':
                 return 0;
-                break;
 
             case 'af':
             case 'bn':