Merge pull request #6191 from kenjis/fix-docs-cli_generators.rst

docs: improve cli_generators.rst

Author: kenjis

user_guide_src/source/cli/cli_generators.rst

@@ -20,6 +20,24 @@ To view the full description and usage information on a particular generator, us
 
 where ``<generator_command>`` will be replaced with the command to check.
 
+.. note:: Do you need to have the generated code in a subfolder? Let's say if you want to create a controller
+    class to reside in the ``Admin`` subfolder of the main ``Controllers`` folder, you will just need
+    to prepend the subfolder to the class name, like this: ``php spark make:controller admin/login``. This
+    command will create the ``Login`` controller in the ``Controllers/Admin`` subfolder with
+    a namespace of ``App\Controllers\Admin``.
+
+.. note:: Working on modules? Code generation will set the root namespace to a default of ``APP_NAMESPACE``.
+    Should you need to have the generated code elsewhere in your module namespace, make sure to set
+    the ``--namespace`` option in your command, e.g., ``php spark make:model blog --namespace Acme\Blog``.
+
+.. warning:: Make sure when setting the ``--namespace`` option that the supplied namespace is a valid
+    namespace defined in your ``$psr4`` array in ``Config\Autoload`` or defined in your composer autoload
+    file. Otherwise, code generation will be interrupted.
+
+.. warning:: Use of ``migrate:create`` to create migration files is now deprecated. It will be removed in
+    future releases. Please use ``make:migration`` as replacement. Also, please use ``make:migration --session``
+    to use instead of the deprecated ``session:migration``.
+
 *******************
 Built-in Generators
 *******************
@@ -94,6 +112,13 @@ Options:
 * ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
+.. note:: If you use ``--suffix``, the generated controller name will be like
+    ``ProductController``. That violates the Controller naming convention
+    when using :ref:`Auto Routing <controller-auto-routing-improved>`
+    (Controller class names MUST start with an uppercase letter and
+    ONLY the first character can be uppercase). So ``--suffix`` can be used
+    when you use :ref:`Defined Routes <defined-route-routing>`.
+
 make:entity
 -----------
 
@@ -226,24 +251,6 @@ Options:
 * ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
-.. note:: Do you need to have the generated code in a subfolder? Let's say if you want to create a controller
-    class to reside in the ``Admin`` subfolder of the main ``Controllers`` folder, you will just need
-    to prepend the subfolder to the class name, like this: ``php spark make:controller admin/login``. This
-    command will create the ``Login`` controller in the ``Controllers/Admin`` subfolder with
-    a namespace of ``App\Controllers\Admin``.
-
-.. note:: Working on modules? Code generation will set the root namespace to a default of ``APP_NAMESPACE``.
-    Should you need to have the generated code elsewhere in your module namespace, make sure to set
-    the ``--namespace`` option in your command, e.g., ``php spark make:model blog --namespace Acme\Blog``.
-
-.. warning:: Make sure when setting the ``--namespace`` option that the supplied namespace is a valid
-    namespace defined in your ``$psr4`` array in ``Config\Autoload`` or defined in your composer autoload
-    file. Otherwise, code generation will be interrupted.
-
-.. warning:: Use of ``migrate:create`` to create migration files is now deprecated. It will be removed in
-    future releases. Please use ``make:migration`` as replacement. Also, please use ``make:migration --session``
-    to use instead of the deprecated ``session:migration``.
-
 ****************************************
 Scaffolding a Complete Set of Stock Code
 ****************************************

user_guide_src/source/incoming/controllers.rst

@@ -144,7 +144,7 @@ controllers. You can extend this class in any new controller.
 
 Then save the file to your **app/Controllers/** directory.
 
-.. important:: The file must be called **Helloworld.php**, with a capital ``H``. Controller class names MUST start with an uppercase letter and ONLY the first character can be uppercase.
+.. important:: The file must be called **Helloworld.php**, with a capital ``H``. When you use Auto Routing, Controller class names MUST start with an uppercase letter and ONLY the first character can be uppercase.
 
 .. important:: A controller method that will be executed by Auto Routing (Improved) needs HTTP verb (``get``, ``post``, ``put``, etc.) prefix like ``getIndex()``, ``postCreate()``.
 
@@ -315,7 +315,7 @@ For security reasons be sure to declare any new utility methods as ``protected``
 
 Then save the file to your **app/Controllers/** directory.
 
-.. important:: The file must be called **Helloworld.php**, with a capital ``H``. Controller class names MUST start with an uppercase letter and ONLY the first character can be uppercase.
+.. important:: The file must be called **Helloworld.php**, with a capital ``H``. When you use Auto Routing, Controller class names MUST start with an uppercase letter and ONLY the first character can be uppercase.
 
 Now visit your site using a URL similar to this::