minor #9194 Make code comments consistent (javiereguiluz)

This PR was merged into the 2.7 branch.

Discussion
----------

Make code comments consistent

This finishes #9088 by doing the opposite change: when the comment describes what the code does instead of what the user must do, use the format: `// returns a ...`  instead of `// return a ...`

Commits
-------

a439f63 Make code comments consistent

Author: javiereguiluz

components/asset.rst

@@ -114,13 +114,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/cache_class_loader.rst

@@ -34,10 +34,10 @@ ApcClassLoader
     // sha1(__FILE__) generates an APC namespace prefix
     $cachedLoader = new ApcClassLoader(sha1(__FILE__), $loader);
 
-    // register the cached class loader
+    // registers the cached class loader
     $cachedLoader->register();
 
-    // deactivate the original, non-cached loader if it was registered previously
+    // deactivates the original, non-cached loader if it was registered previously
     $loader->unregister();
 
 XcacheClassLoader
@@ -54,10 +54,10 @@ it is straightforward::
     // sha1(__FILE__) generates an XCache namespace prefix
     $cachedLoader = new XcacheClassLoader(sha1(__FILE__), $loader);
 
-    // register the cached class loader
+    // registers the cached class loader
     $cachedLoader->register();
 
-    // deactivate the original, non-cached loader if it was registered previously
+    // deactivates the original, non-cached loader if it was registered previously
     $loader->unregister();
 
 .. _APC:        http://php.net/manual/en/book.apc.php

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

@@ -40,19 +40,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();
     });
 
@@ -74,12 +74,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();
 
@@ -112,10 +112,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()));
     });
 
@@ -138,16 +138,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();
 
 Instead of advancing the bar by a number of steps (with the

components/console/helpers/table.rst

@@ -111,14 +111,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:
@@ -136,10 +136,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/console/single_command_tool.rst

@@ -35,7 +35,7 @@ it is possible to remove this need by extending the application::
          */
         protected function getDefaultCommands()
         {
-            // Keep the core default commands to have the HelpCommand
+            // Keeps the core default commands to have the HelpCommand
             // which is used when using the --help option
             $defaultCommands = parent::getDefaultCommands();
 
@@ -51,7 +51,7 @@ it is possible to remove this need by extending the application::
         public function getDefinition()
         {
             $inputDefinition = parent::getDefinition();
-            // clear out the normal first argument, which is the command name
+            // clears out the normal first argument, which is the command name
             $inputDefinition->setArguments();
 
             return $inputDefinition;

components/dom_crawler.rst

@@ -87,7 +87,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;
         });
 
@@ -196,7 +196,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::
@@ -317,7 +317,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::
@@ -368,13 +368,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,
@@ -391,10 +391,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'
@@ -406,17 +406,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
@@ -445,7 +445,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');
 
@@ -454,7 +454,7 @@ directly::
     $form['login'] = 'symfonyfan';
     $form['password'] = 'anypass';
 
-    // submit that form
+    // submits the given form
     $crawler = $client->submit($form);
 
 .. _components-dom-crawler-invalid:
@@ -467,10 +467,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

@@ -206,18 +206,18 @@ determine which instance is passed.
         $containerBuilder = new ContainerBuilder(new ParameterBag());
         $containerBuilder->addCompilerPass(new RegisterListenersPass());
 
-        // register the event dispatcher service
+        // registers the event dispatcher service
         $containerBuilder->register('event_dispatcher', ContainerAwareEventDispatcher::class)
             ->addArgument(new Reference('service_container'));
 
-        // register your event listener service
+        // registers your event listener service
         $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');
 
@@ -302,7 +302,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);