Merge branch '2.8' into 3.4

* 2.8:
  Minor reword in the performance article
  Always use PHPUnit Bridge to run tests
  Recommend to never inline PHPDoc blocks
  Added links to the roadmap of each Symfony version
  Documented the PhpExecutableFinder utility
  Fix references to annotation loader tip
  Make code comments consistent

Author: javiereguiluz

components/asset.rst

@@ -121,13 +121,13 @@ suffix to any asset path::
 In case you want to modify the version format, pass a sprintf-compatible format
 string as the second argument of the ``StaticVersionStrategy`` constructor::
 
-    // put the 'version' word before the version value
+    // puts the 'version' word before the version value
     $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s'));
 
     echo $package->getUrl('/image.png');
     // result: /image.png?version=v1
 
-    // put the asset version before its path
+    // puts the asset version before its path
     $package = new Package(new StaticVersionStrategy('v1', '%2$s/%1$s'));
 
     echo $package->getUrl('/image.png');

components/class_loader/class_loader.rst

@@ -40,13 +40,13 @@ your classes::
     // register a single namespaces
     $loader->addPrefix('Symfony', __DIR__.'/vendor/symfony/symfony/src');
 
-    // register several namespaces at once
+    // registers several namespaces at once
     $loader->addPrefixes(array(
         'Symfony' => __DIR__.'/../vendor/symfony/symfony/src',
         'Monolog' => __DIR__.'/../vendor/monolog/monolog/src',
     ));
 
-    // register a prefix for a class following the PEAR naming conventions
+    // registers a prefix for a class following the PEAR naming conventions
     $loader->addPrefix('Twig_', __DIR__.'/vendor/twig/twig/lib');
 
     $loader->addPrefixes(array(

components/console/events.rst

@@ -37,19 +37,19 @@ dispatched. Listeners receive a
     use Symfony\Component\Console\ConsoleEvents;
 
     $dispatcher->addListener(ConsoleEvents::COMMAND, function (ConsoleCommandEvent $event) {
-        // get the input instance
+        // gets the input instance
         $input = $event->getInput();
 
-        // get the output instance
+        // gets the output instance
         $output = $event->getOutput();
 
-        // get the command to be executed
+        // gets the command to be executed
         $command = $event->getCommand();
 
-        // write something about the command
+        // writes something about the command
         $output->writeln(sprintf('Before running command <info>%s</info>', $command->getName()));
 
-        // get the application
+        // gets the application
         $application = $command->getApplication();
     });
 
@@ -68,12 +68,12 @@ C/C++ standard.::
     use Symfony\Component\Console\ConsoleEvents;
 
     $dispatcher->addListener(ConsoleEvents::COMMAND, function (ConsoleCommandEvent $event) {
-        // get the command to be executed
+        // gets the command to be executed
         $command = $event->getCommand();
 
         // ... check if the command can be executed
 
-        // disable the command, this will result in the command being skipped
+        // disables the command, this will result in the command being skipped
         // and code 113 being returned from the Application
         $event->disableCommand();
 
@@ -110,10 +110,10 @@ Listeners receive a
 
         $output->writeln(sprintf('Oops, exception thrown while running command <info>%s</info>', $command->getName()));
 
-        // get the current exit code (the exception code or the exit code set by a ConsoleEvents::TERMINATE event)
+        // gets the current exit code (the exception code or the exit code set by a ConsoleEvents::TERMINATE event)
         $exitCode = $event->getExitCode();
 
-        // change the exception to another one
+        // changes the exception to another one
         $event->setException(new \LogicException('Caught exception', $exitCode, $event->getException()));
     });
 
@@ -149,16 +149,16 @@ Listeners receive a
     use Symfony\Component\Console\ConsoleEvents;
 
     $dispatcher->addListener(ConsoleEvents::TERMINATE, function (ConsoleTerminateEvent $event) {
-        // get the output
+        // gets the output
         $output = $event->getOutput();
 
-        // get the command that has been executed
+        // gets the command that has been executed
         $command = $event->getCommand();
 
-        // display something
+        // displays the given content
         $output->writeln(sprintf('After running command <info>%s</info>', $command->getName()));
 
-        // change the exit code
+        // changes the exit code
         $event->setExitCode(128);
     });
 

components/console/helpers/progressbar.rst

@@ -15,24 +15,24 @@ number of units, and advance the progress as the command executes::
 
     use Symfony\Component\Console\Helper\ProgressBar;
 
-    // create a new progress bar (50 units)
+    // creates a new progress bar (50 units)
     $progress = new ProgressBar($output, 50);
 
-    // start and displays the progress bar
+    // starts and displays the progress bar
     $progress->start();
 
     $i = 0;
     while ($i++ < 50) {
         // ... do some work
 
-        // advance the progress bar 1 unit
+        // advances the progress bar 1 unit
         $progress->advance();
 
         // you can also advance the progress bar by more than 1 unit
         // $progress->advance(3);
     }
 
-    // ensure that the progress bar is at 100%
+    // ensures that the progress bar is at 100%
     $progress->finish();
 
 .. tip::

components/console/helpers/table.rst

@@ -150,14 +150,14 @@ If the built-in styles do not fit your need, define your own::
     // by default, this is based on the default style
     $style = new TableStyle();
 
-    // customize the style
+    // customizes the style
     $style
         ->setHorizontalBorderChar('<fg=magenta>|</>')
         ->setVerticalBorderChar('<fg=magenta>-</>')
         ->setCrossingChar(' ')
     ;
 
-    // use the style for this table
+    // uses the custom style for this table
     $table->setStyle($style);
 
 Here is a full list of things you can customize:
@@ -175,10 +175,10 @@ Here is a full list of things you can customize:
 
     You can also register a style globally::
 
-        // register the style under the colorful name
+        // registers the style under the colorful name
         Table::setStyleDefinition('colorful', $style);
 
-        // use it for a table
+        // applies the custom style for the given table
         $table->setStyle('colorful');
 
     This method can also be used to override a built-in style.

components/dom_crawler.rst

@@ -89,7 +89,7 @@ An anonymous function can be used to filter with more complex criteria::
     $crawler = $crawler
         ->filter('body > p')
         ->reduce(function (Crawler $node, $i) {
-            // filter every other node
+            // filters every other node
             return ($i % 2) == 0;
         });
 
@@ -185,7 +185,7 @@ Accessing Node Values
 
 Access the node name (HTML tag name) of the first node of the current selection (eg. "p" or "div")::
 
-    // will return the node name (HTML tag name) of the first child element under <body>
+    // returns the node name (HTML tag name) of the first child element under <body>
     $tag = $crawler->filterXPath('//body/*')->nodeName();
 
 Access the value of the first node of the current selection::
@@ -367,7 +367,7 @@ instance with just the selected link(s). Calling ``link()`` gives you a special
 The :class:`Symfony\\Component\\DomCrawler\\Link` object has several useful
 methods to get more information about the selected link itself::
 
-    // return the proper URI that can be used to make another request
+    // returns the proper URI that can be used to make another request
     $uri = $link->getUri();
 
 .. note::
@@ -441,13 +441,13 @@ attribute followed by a query string of all of the form's values.
 
 You can virtually set and get values on the form::
 
-    // set values on the form internally
+    // sets values on the form internally
     $form->setValues(array(
         'registration[username]' => 'symfonyfan',
         'registration[terms]'    => 1,
     ));
 
-    // get back an array of values - in the "flat" array like above
+    // gets back an array of values - in the "flat" array like above
     $values = $form->getValues();
 
     // returns the values like PHP would see them,
@@ -464,10 +464,10 @@ To work with multi-dimensional fields::
 
 Pass an array of values::
 
-    // Set a single field
+    // sets a single field
     $form->setValues(array('multi' => array('value')));
 
-    // Set multiple fields at once
+    // sets multiple fields at once
     $form->setValues(array('multi' => array(
         1             => 'value',
         'dimensional' => 'an other value'
@@ -479,17 +479,17 @@ and uploading files::
 
     $form['registration[username]']->setValue('symfonyfan');
 
-    // check or uncheck a checkbox
+    // checks or unchecks a checkbox
     $form['registration[terms]']->tick();
     $form['registration[terms]']->untick();
 
-    // select an option
+    // selects an option
     $form['registration[birthday][year]']->select(1984);
 
-    // select many options from a "multiple" select
+    // selects many options from a "multiple" select
     $form['registration[interests]']->select(array('symfony', 'cookies'));
 
-    // even fake a file upload
+    // fakes a file upload
     $form['registration[photo]']->upload('/path/to/lucas.jpg');
 
 Using the Form Data
@@ -518,7 +518,7 @@ directly::
 
     use Goutte\Client;
 
-    // make a real request to an external site
+    // makes a real request to an external site
     $client = new Client();
     $crawler = $client->request('GET', 'https://github.com/login');
 
@@ -527,7 +527,7 @@ directly::
     $form['login'] = 'symfonyfan';
     $form['password'] = 'anypass';
 
-    // submit that form
+    // submits the given form
     $crawler = $client->submit($form);
 
 .. _components-dom-crawler-invalid:
@@ -540,10 +540,10 @@ to prevent you from setting invalid values. If you want to be able to set
 invalid values, you can use the  ``disableValidation()`` method on either
 the whole form or specific field(s)::
 
-    // Disable validation for a specific field
+    // disables validation for a specific field
     $form['country']->disableValidation()->select('Invalid value');
 
-    // Disable validation for the whole form
+    // disables validation for the whole form
     $form->disableValidation();
     $form['country']->select('Invalid value');
 

components/event_dispatcher.rst

@@ -207,14 +207,14 @@ determine which instance is passed.
 
         $containerBuilder->register('event_dispatcher', EventDispatcher::class);
 
-        // register an event listener
+        // registers an event listener
         $containerBuilder->register('listener_service_id', \AcmeListener::class)
             ->addTag('kernel.event_listener', array(
                 'event' => 'acme.foo.action',
                 'method' => 'onFooAction',
             ));
 
-        // register an event subscriber
+        // registers an event subscriber
         $containerBuilder->register('subscriber_service_id', \AcmeSubscriber::class)
             ->addTag('kernel.event_subscriber');
 
@@ -299,7 +299,7 @@ each listener of that event::
     $order = new Order();
     // ...
 
-    // create the OrderPlacedEvent and dispatch it
+    // creates the OrderPlacedEvent and dispatches it
     $event = new OrderPlacedEvent($order);
     $dispatcher->dispatch(OrderPlacedEvent::NAME, $event);
 

components/event_dispatcher/traceable_dispatcher.rst

@@ -27,7 +27,7 @@ to register event listeners and dispatch events::
 
     // ...
 
-    // register an event listener
+    // registers an event listener
     $eventListener = ...;
     $priority = ...;
     $traceableEventDispatcher->addListener(
@@ -36,7 +36,7 @@ to register event listeners and dispatch events::
         $priority
     );
 
-    // dispatch an event
+    // dispatches an event
     $event = ...;
     $traceableEventDispatcher->dispatch('event.the_name', $event);
 

components/expression_language/extending.rst

@@ -132,7 +132,7 @@ or by using the second argument of the constructor::
         {
             public function __construct(ParserCacheInterface $parser = null, array $providers = array())
             {
-                // prepend the default provider to let users override it easily
+                // prepends the default provider to let users override it easily
                 array_unshift($providers, new StringExpressionLanguageProvider());
 
                 parent::__construct($parser, $providers);