Merge pull request #6960 from kenjis/fix-docs-routing.rst

docs: improve routing.rst

Author: samsonasik

user_guide_src/source/incoming/routing.rst

@@ -32,13 +32,42 @@ If you expect a GET request, you use the ``get()`` method:
 .. literalinclude:: routing/001.php
 
 A route takes the URI path (``/``) on the left, and maps it to the controller and method (``Home::index``) on the right,
-along with any parameters that should be passed to the controller. The controller and method should
+along with any parameters that should be passed to the controller.
+
+The controller and method should
 be listed in the same way that you would use a static method, by separating the class
-and its method with a double-colon, like ``Users::list``. If that method requires parameters to be
+and its method with a double-colon, like ``Users::list``.
+
+If that method requires parameters to be
 passed to it, then they would be listed after the method name, separated by forward-slashes:
 
 .. literalinclude:: routing/002.php
 
+Examples
+========
+
+Here are a few basic routing examples.
+
+A URL containing the word **journals** in the first segment will be mapped to the ``\App\Controllers\Blogs`` class,
+and the default method, which is usually ``index()``:
+
+.. literalinclude:: routing/006.php
+
+A URL containing the segments **blog/joe** will be mapped to the ``\App\Controllers\Blogs`` class and the ``users()`` method.
+The ID will be set to ``34``:
+
+.. literalinclude:: routing/007.php
+
+A URL with **product** as the first segment, and anything in the second will be mapped to the ``\App\Controllers\Catalog`` class
+and the ``productLookup()`` method:
+
+.. literalinclude:: routing/008.php
+
+A URL with **product** as the first segment, and a number in the second will be mapped to the ``\App\Controllers\Catalog`` class
+and the ``productLookupByID()`` method passing in the match as a variable to the method:
+
+.. literalinclude:: routing/009.php
+
 HTTP verbs
 ==========
 
@@ -99,31 +128,6 @@ Placeholders Description
 .. note:: ``{locale}`` cannot be used as a placeholder or other part of the route, as it is reserved for use
     in :doc:`localization </outgoing/localization>`.
 
-Examples
-========
-
-Here are a few basic routing examples.
-
-A URL containing the word **journals** in the first segment will be mapped to the ``\App\Controllers\Blogs`` class,
-and the default method, which is usually ``index()``:
-
-.. literalinclude:: routing/006.php
-
-A URL containing the segments **blog/joe** will be mapped to the ``\App\Controllers\Blogs`` class and the ``users()`` method.
-The ID will be set to ``34``:
-
-.. literalinclude:: routing/007.php
-
-A URL with **product** as the first segment, and anything in the second will be mapped to the ``\App\Controllers\Catalog`` class
-and the ``productLookup()`` method:
-
-.. literalinclude:: routing/008.php
-
-A URL with **product** as the first segment, and a number in the second will be mapped to the ``\App\Controllers\Catalog`` class
-and the ``productLookupByID()`` method passing in the match as a variable to the method:
-
-.. literalinclude:: routing/009.php
-
 Note that a single ``(:any)`` will match multiple segments in the URL if present. For example the route:
 
 .. literalinclude:: routing/010.php
@@ -133,6 +137,9 @@ Controller should take into account the maximum parameters:
 
 .. literalinclude:: routing/011.php
 
+.. important:: Do not put any placeholder after ``(:any)``. Because the number of
+    parameters passed to the controller method may change.
+
 If matching multiple segments is not the intended behavior, ``(:segment)`` should be used when defining the
 routes. With the examples URLs from above:
 
@@ -188,7 +195,7 @@ is allowed, as are back-references.
 
     .. literalinclude:: routing/018.php
 
-In the above example, a URI similar to **products/shirts/123** would instead call the ``show`` method
+In the above example, a URI similar to **products/shirts/123** would instead call the ``show()`` method
 of the ``Products`` controller class, with the original first and second segment passed as arguments to it.
 
 With regular expressions, you can also catch a segment containing a forward slash (``/``), which would usually
@@ -202,7 +209,7 @@ redirect them back to the same page after they log in, you may find this example
 For those of you who don't know regular expressions and want to learn more about them,
 `regular-expressions.info <https://www.regular-expressions.info/>`_ might be a good starting point.
 
-.. important:: Note: You can also mix and match wildcards with regular expressions.
+.. note:: You can also mix and match placeholders with regular expressions.
 
 Closures
 ========