minor #10535 review doc chapters for belittling words (dbu)

This PR was merged into the 4.1 branch.

Discussion
----------

review doc chapters for belittling words

and a rather hefty chunk of changes for symfony/diversity#9

i hope this one has not gotten too big.

Commits
-------

84e6684 review doc chapter for belittling words

Author: javiereguiluz

bundles/best_practices.rst

@@ -23,7 +23,7 @@ vendor segment, followed by zero or more category segments, and it ends with the
 namespace short name, which must end with ``Bundle``.
 
 A namespace becomes a bundle as soon as you add a bundle class to it. The
-bundle class name must follow these simple rules:
+bundle class name must follow these rules:
 
 * Use only alphanumeric characters and underscores;
 * Use a StudlyCaps name (i.e. camelCase with the first letter uppercased);
@@ -467,8 +467,9 @@ Retrieve the configuration parameters in your code from the container::
 
     $container->getParameter('acme_blog.author.email');
 
-Even if this mechanism is simple enough, you should consider using the more
-advanced :doc:`semantic bundle configuration </bundles/configuration>`.
+While this mechanism requires the least effort, you should consider using the
+more advanced :doc:`semantic bundle configuration </bundles/configuration>` to
+make your configuration more robust.
 
 Versioning
 ----------

bundles/override.rst

@@ -68,7 +68,7 @@ the routes from any bundle, then they must be manually imported from somewhere
 in your application (e.g. ``config/routes.yaml``).
 
 The easiest way to "override" a bundle's routing is to never import it at
-all. Instead of importing a third-party bundle's routing, simply copy
+all. Instead of importing a third-party bundle's routing, copy
 that routing file into your application, modify it, and import it instead.
 
 Controllers

configuration/configuration_organization.rst

@@ -5,7 +5,7 @@ How to Organize Configuration Files
 ===================================
 
 The Symfony skeleton defines three :doc:`execution environments </configuration/environments>`
-called ``dev``, ``prod`` and ``test``. An environment simply represents a way
+called ``dev``, ``prod`` and ``test``. An environment represents a way
 to execute the same codebase with different configurations.
 
 In order to select the configuration file to load for each environment, Symfony
@@ -129,9 +129,9 @@ Global Configuration Files
 
 Some system administrators may prefer to store sensitive parameters in files
 outside the project directory. Imagine that the database credentials for your
-website are stored in the ``/etc/sites/mysite.com/parameters.yaml`` file. Loading
-this file is as simple as indicating the full file path when importing it from
-any other configuration file:
+website are stored in the ``/etc/sites/mysite.com/parameters.yaml`` file. You
+can load files from outside the project folder by indicating the full file path
+when importing it from any other configuration file:
 
 .. configuration-block::
 

configuration/environments.rst

@@ -199,7 +199,7 @@ Creating a new Environment
 --------------------------
 
 Since an environment is nothing more than a string that corresponds to a set of
-configuration, creating a new environment is quite easy.
+configuration, you can also create your own environments for specific purposes.
 
 Suppose, for example, that before deployment, you need to benchmark your
 application. One way to benchmark the application is to use near-production
@@ -355,7 +355,7 @@ includes the following:
 
 .. note::
 
-    You can easily change the directory location and name. For more information
+    You can change the directory location and name. For more information
     read the article :doc:`/configuration/override_dir_structure`.
 
 Going further

configuration/front_controllers_and_kernel.rst

@@ -51,7 +51,7 @@ You can choose the front controller that's used by adding it in the URL, like:
      http://localhost/index.php/some/path/...
 
 As you can see, this URL contains the PHP script to be used as the front
-controller. You can use that to easily switch to a custom made front controller
+controller. You can use that to switch to a custom made front controller
 that is located in the ``public/`` directory.
 
 .. seealso::
@@ -123,7 +123,7 @@ controller to make use of the new kernel.
 The Environments
 ----------------
 
-As just mentioned, the ``Kernel`` has to implement another method -
+As mentioned above, the ``Kernel`` has to implement another method -
 :method:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait::configureContainer`.
 This method is responsible for loading the application's configuration from the
 right *environment*.

configuration/micro_kernel_trait.rst

@@ -5,8 +5,8 @@ The default ``Kernel`` class included in Symfony applications uses a
 :class:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait` to configure
 the bundles, the routes and the service container in the same class.
 
-This micro-kernel approach is so flexible that let you control your application
-structure and features quite easily.
+This micro-kernel approach is flexible, allowing you to control your application
+structure and features.
 
 A Single-File Symfony Application
 ---------------------------------

configuration/multiple_kernels.rst

@@ -124,7 +124,7 @@ According to the above code, this config will live in one or multiple files
 stored in ``config/api/`` and ``config/api/ENVIRONMENT_NAME/`` directories.
 
 The new configuration files can be created from scratch when you load just a few
-bundles, because it will be very simple. Otherwise, duplicate the existing
+bundles, because it will be small. Otherwise, duplicate the existing
 config files in ``config/packages/`` or better, import them and override the
 needed options.
 

configuration/override_dir_structure.rst

@@ -5,7 +5,7 @@ How to Override Symfony's default Directory Structure
 =====================================================
 
 Symfony automatically ships with a default directory structure. You can
-easily override this directory structure to create your own. The default
+override this directory structure to create your own. The default
 directory structure is:
 
 .. code-block:: text

console/input.rst

@@ -71,7 +71,7 @@ to greet all your friends). Only the last argument can be a list::
             'Who do you want to greet (separate multiple names with a space)?'
         );
 
-To use this, just specify as many names as you want:
+To use this, specify as many names as you want:
 
 .. code-block:: terminal
 

console/lazy_commands.rst

@@ -42,7 +42,7 @@ Built-in Command Loaders
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :class:`Symfony\\Component\\Console\\CommandLoader\\FactoryCommandLoader`
-class provides a simple way of getting commands lazily loaded as it takes an
+class provides a way of getting commands lazily loaded as it takes an
 array of ``Command`` factories as its only constructor argument::
 
     use Symfony\Component\Console\CommandLoader\FactoryCommandLoader;

console/style.rst

@@ -336,7 +336,7 @@ Defining your Own Styles
 ------------------------
 
 If you don't like the design of the commands that use the Symfony Style, you can
-define your own set of console styles. Just create a class that implements the
+define your own set of console styles. Create a class that implements the
 :class:`Symfony\\Component\\Console\\Style\\StyleInterface`::
 
     namespace App\Console;

contributing/code/git.rst

@@ -10,7 +10,7 @@ Pull Requests
 Whenever a pull request is merged, all the information contained in the pull
 request (including comments) is saved in the repository.
 
-You can easily spot pull request merges as the commit message always follows
+You can identify pull request merges as the commit message always follows
 this pattern:
 
 .. code-block:: text

contributing/code/reproducer.rst

@@ -63,7 +63,7 @@ to a route definition. Then, after creating your project:
 #. Don't edit any of the default Symfony configuration options.
 #. Don't copy your original application code and don't use the same structure
    of controllers, actions, etc. as in your original application.
-#. Create a simple controller and add your routing definition that shows the bug.
+#. Create a small controller and add your routing definition that shows the bug.
 #. Don't create or modify any other file.
 #. Execute ``composer require symfony/web-server-bundle`` and use the ``server:run``
    command to browse to the new route and see if the bug appears or not.

contributing/community/review-comments.rst

@@ -26,7 +26,7 @@ constructive, respectful and helpful reviews and replies.
     your ideas and opinions but helping you to better communicate,
     prevent possible confusion, and keeping the Symfony community a
     welcoming place for everyone. **You are free to disagree with
-    someone's opinions, just don't be disrespectful.**
+    someone's opinions, but don't be disrespectful.**
 
 First of, accept that many programming decisions are opinions.
 Discuss trade offs, which you prefer, and reach a resolution quickly.

controller/error_pages.rst

@@ -11,7 +11,7 @@ exception in your code.
 
 In the :doc:`development environment </configuration/environments>`,
 Symfony catches all the exceptions and displays a special **exception page**
-with lots of debug information to help you quickly discover the root problem:
+with lots of debug information to help you discover the root problem:
 
 .. image:: /_images/controller/error_pages/exceptions-in-dev-environment.png
    :alt: A typical exception page in the development environment
@@ -198,7 +198,7 @@ If you need a little more flexibility beyond just overriding the template,
 then you can change the controller that renders the error page. For example,
 you might need to pass some additional variables into your template.
 
-To do this, simply create a new controller anywhere in your application and set
+To do this, create a new controller anywhere in your application and set
 the :ref:`twig.exception_controller <config-twig-exception-controller>`
 configuration option to point to it:
 
@@ -249,8 +249,8 @@ will be passed two parameters:
     A :class:`\\Symfony\\Component\\HttpKernel\\Log\\DebugLoggerInterface`
     instance which may be ``null`` in some circumstances.
 
-Instead of creating a new exception controller from scratch you can, of course,
-also extend the default :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`.
+Instead of creating a new exception controller from scratch you can also extend
+the default :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`.
 In that case, you might want to override one or both of the ``showAction()`` and
 ``findTemplate()`` methods. The latter one locates the template to be used.
 

controller/service.rst

@@ -75,7 +75,7 @@ Invokable Controllers
 ---------------------
 
 If your controller implements the ``__invoke()`` method - popular with the
-Action-Domain-Response (ADR) pattern, you can simply refer to the service id
+Action-Domain-Response (ADR) pattern, you can refer to the service id
 without the method (``App\Controller\HelloController`` for example).
 
 Alternatives to base Controller Methods

controller/soap_web_service.rst

@@ -6,8 +6,8 @@
 How to Create a SOAP Web Service in a Symfony Controller
 ========================================================
 
-Setting up a controller to act as a SOAP server is simple with a couple
-tools. You must, of course, have the `PHP SOAP`_ extension installed.
+Setting up a controller to act as a SOAP server is aided by a couple
+tools. Those tools expect you to have the `PHP SOAP`_ extension installed.
 As the PHP SOAP extension cannot currently generate a WSDL, you must either
 create one from scratch or use a 3rd party generator.
 

create_framework/event_dispatcher.rst

@@ -248,8 +248,8 @@ issue: the knowledge of the priorities is "hardcoded" in the front controller,
 instead of being in the listeners themselves. For each application, you have
 to remember to set the appropriate priorities. Moreover, the listener method
 names are also exposed here, which means that refactoring our listeners would
-mean changing all the applications that rely on those listeners. Of course,
-there is a solution: use subscribers instead of listeners::
+mean changing all the applications that rely on those listeners. The solution
+to this dilemma is to use subscribers instead of listeners::
 
     $dispatcher = new EventDispatcher();
     $dispatcher->addSubscriber(new Simplex\ContentLengthListener());

create_framework/front_controller.rst

@@ -61,7 +61,7 @@ which name is exposed to the end user via the URL
 (``http://127.0.0.1:4321/bye.php``): there is a direct mapping between the PHP
 script name and the client URL. This is because the dispatching of the request
 is done by the web server directly. It might be a good idea to move this
-dispatching to our code for better flexibility. This can be easily achieved by
+dispatching to our code for better flexibility. This can be achieved by
 routing all client requests to a single PHP script.
 
 .. tip::

create_framework/http_foundation.rst

@@ -201,7 +201,7 @@ You can also simulate a request::
 
     $request = Request::create('/index.php?name=Fabien');
 
-With the ``Response`` class, you can easily tweak the response::
+With the ``Response`` class, you can tweak the response::
 
     $response = new Response();
 

create_framework/http_kernel_controller_resolver.rst

@@ -109,7 +109,7 @@ correctly::
     public function index($request)
 
 More interesting, ``getArguments()`` is also able to inject any Request
-attribute; the argument just needs to have the same name as the corresponding
+attribute; if the argument has the same name as the corresponding
 attribute::
 
     public function index($year)
@@ -127,7 +127,7 @@ optional attribute of the Request::
 
     public function index($year = 2012)
 
-Let's just inject the ``$year`` request attribute for our controller::
+Let's inject the ``$year`` request attribute for our controller::
 
     class LeapYearController
     {

create_framework/http_kernel_httpkernel_class.rst

@@ -104,8 +104,8 @@ The error controller reads as follows::
         }
     }
 
-Voilà! Clean and customizable error management without efforts. And of course,
-if your controller throws an exception, HttpKernel will handle it nicely.
+Voilà! Clean and customizable error management without efforts. And
+if your ``ErrorController`` throws an exception, HttpKernel will handle it nicely.
 
 In chapter two, we talked about the ``Response::prepare()`` method, which
 ensures that a Response is compliant with the HTTP specification. It is
@@ -115,8 +115,7 @@ client; that's what the ``ResponseListener`` does::
     $dispatcher->addSubscriber(new HttpKernel\EventListener\ResponseListener('UTF-8'));
 
 This one was easy too! Let's take another one: do you want out of the box
-support for streamed responses? Just subscribe to
-``StreamedResponseListener``::
+support for streamed responses? Subscribe to ``StreamedResponseListener``::
 
     $dispatcher->addSubscriber(new HttpKernel\EventListener\StreamedResponseListener());
 

create_framework/http_kernel_httpkernelinterface.rst

@@ -92,7 +92,7 @@ to cache a response for 10 seconds, use the ``Response::setTtl()`` method::
 
     If, like me, you are running your framework from the command line by
     simulating requests (``Request::create('/is_leap_year/2012')``), you can
-    easily debug Response instances by dumping their string representation
+    debug Response instances by dumping their string representation
     (``echo $response;``) as it displays all headers as well as the response
     content.
 
@@ -113,9 +113,9 @@ expiration and the validation models of the HTTP specification. If you are not
 comfortable with these concepts, read the `HTTP caching`_ chapter of the
 Symfony documentation.
 
-The Response class contains many other methods that let you configure the
-HTTP cache very easily. One of the most powerful is ``setCache()`` as it
-abstracts the most frequently used caching strategies into one simple array::
+The Response class contains methods that let you configure the
+HTTP cache. One of the most powerful is ``setCache()`` as it
+abstracts the most frequently used caching strategies into a single array::
 
     $date = date_create_from_format('Y-m-d H:i:s', '2005-10-15 10:00:00');
 
@@ -135,7 +135,7 @@ abstracts the most frequently used caching strategies into one simple array::
     $response->setSharedMaxAge(10);
 
 When using the validation model, the ``isNotModified()`` method allows you to
-easily cut on the response time by short-circuiting the response generation as
+cut on the response time by short-circuiting the response generation as
 early as possible::
 
     $response->setETag('whatever_you_compute_as_an_etag');

create_framework/introduction.rst

@@ -38,7 +38,7 @@ you can use as is or as a start for your very own. It will start with a simple
 framework and more features will be added with time. Eventually, you will have
 a fully-featured full-stack web framework.
 
-And of course, each step will be the occasion to learn more about some of the
+And each step will be the occasion to learn more about some of the
 Symfony Components.
 
 Many modern web frameworks advertize themselves as being MVC frameworks. This

create_framework/routing.rst

@@ -189,7 +189,8 @@ more flexible than the previous one. Enjoy!
 Using the Routing component has one big additional benefit: the ability to
 generate URLs based on Route definitions. When using both URL matching and URL
 generation in your code, changing the URL patterns should have no other
-impact. Want to know how to use the generator? Insanely easy::
+impact. Want to know how to use the generator? Calling the ``generate`` method
+is all it takes::
 
     use Symfony\Component\Routing;
 

create_framework/templating.rst

@@ -69,7 +69,7 @@ the ``_controller`` route attribute::
         $response = new Response('An error occurred', 500);
     }
 
-A route can now be associated with any controller and of course, within a
+A route can now be associated with any controller and within a
 controller, you can still use the ``render_template()`` to render a template::
 
     $routes->add('hello', new Routing\Route('/hello/{name}', array(
@@ -138,7 +138,7 @@ application that needs some simple logic. Our application has one page that
 says whether a given year is a leap year or not. When calling
 ``/is_leap_year``, you get the answer for the current year, but you can
 also specify a year like in ``/is_leap_year/2009``. Being generic, the
-framework does not need to be modified in any way, just create a new
+framework does not need to be modified in any way, create a new
 ``app.php`` file::
 
     // example.com/src/app.php
@@ -169,7 +169,7 @@ framework does not need to be modified in any way, just create a new
 
 The ``is_leap_year()`` function returns ``true`` when the given year is a leap
 year, ``false`` otherwise. If the year is ``null``, the current year is
-tested. The controller is simple: it gets the year from the request
+tested. The controller does little: it gets the year from the request
 attributes, pass it to the ``is_leap_year()`` function, and according to the
 return value it creates a new Response object.
 

create_framework/unit_testing.rst

@@ -121,8 +121,7 @@ This test simulates a request that does not match any route. As such, the
 ``match()`` method returns a ``ResourceNotFoundException`` exception and we
 are testing that our framework converts this exception to a 404 response.
 
-Executing this test is as simple as running ``phpunit`` from the
-``example.com`` directory:
+Execute this test by running ``phpunit`` in the ``example.com`` directory:
 
 .. code-block:: terminal
 
@@ -136,7 +135,8 @@ Executing this test is as simple as running ``phpunit`` from the
 After the test ran, you should see a green bar. If not, you have a bug
 either in the test or in the framework code!
 
-Adding a unit test for any exception thrown in a controller is just as easy::
+Adding a unit test for any exception thrown in a controller means expecting a
+response code of 500::
 
     public function testErrorHandling()
     {
@@ -209,7 +209,7 @@ Alternatively you can output the result directly to the console:
 
     $ phpunit --coverage-text
 
-Thanks to the simple object-oriented code that we have written so far, we have
+Thanks to the clean object-oriented code that we have written so far, we have
 been able to write unit-tests to cover all possible use cases of our
 framework; test doubles ensured that we were actually testing our code and not
 Symfony code.