update-readme-v2.28

Author: Ken van der Eerden

README.md

@@ -140,38 +140,54 @@ For extra documentation you can use markdown inside your controller method as we
 </p>
 
 
-# Extra
+# Extra documentation
 
-You write extra documentation in markdown which will be rendered as HTML on the dashboard.
-Example of using it in the controller
+You can write extra documentation in markdown using `@lrd` in the PHPDoc on the `rules` method of the `Request` classes and on the controller methods.\
+This will then be rendered as HTML on the dashboard.\
+Documentation defined on the controller method is appended below documentation defined on the `rules` method.\
+Example of using it in the controller:
 
 ```php
  /**
  * @lrd:start
- * Hello markdown
+ * # Hello markdown
  * Free `code` or *text* to write documentation in markdown
  * @lrd:end
  */
  public function index(MyIndexRequest $request): Resource
  {
 ```
 
-# Params not in rules
+# Extra parameters
 
-You write extra params with rules with @LRDparam in the comment line as one line
+You define extra parameters using `@LRDparam`.\
+You can use `@LRDparam` in PHPDoc on both the `rules` methods and the controller methods.\
+You can also overwrite rules using `@LRDparam`.
+Meaning, when rules are defined in the `rules` method, you can overwrite those rules using `@LRDparam` in the PHPDoc above the `rules` method.
+And you can overwrite those rules using `@LRDparam` in a PHPDoc on the controller methods.\
+So, the precedence is `Controller method PHPDoc` < `Rules method PHPDoc` < `Rules method values`. 
 
 ```php
  /**
  * @LRDparam username string|max:32
  * // either space or pipe
  * @LRDparam nickaname string|nullable|max:32
  * // override the default response codes
- * @LRDparam responses 200,422
+ * @LRDresponses 200|422
  */
  public function index(MyIndexRequest $request): Resource
  {
 ```
 
+# Response codes
+Without explicitly declaring response codes, 
+all routes are documented to return any of the response codes defined in the request-docs.php `default_responses` configuration.\
+However, using `@LRDresponse 200|422` (spaces or pipes) within the PHPDoc on your controller methods,
+you are able to explicitly define what status codes can be returned by the server.
+
+# Configuration
+Please view the `request-docs.php` config file to see how you can customise your experience.
+
 # Testing
 
 ```bash
@@ -231,6 +247,7 @@ Fixing lints
 - v2.16 Top Navbar is fixed
 - v2.19 Publish _astro assets
 - v2.25 `laravel-request-docs:export` command to export
+- v2.28 Allow extra documentation to be defined on the `rules` method of the Request class by @Ken-vdE
 
 
 # Contributors