Update docs

Author: shalvah

docs/architecture.md

@@ -1,4 +1,12 @@
-# Architecutre
+# Architecture
 Read this page if you want a deeper understanding of how this works (for instance, for the purpose of contributing).
 
-- Documentarian takes in a markdwown file and transforms it into HTML.
+- When the `generate` command is run, it fetches all your application's routes from Laravel's (or DIngo's) Route facade.
+- Next, the RouteMatcher uses the rules in your config to determine what routes to generate documentation for, as well as extract any specific configuration for them. This configuration is passed to the next stages.
+- The Generator processes each route. This entails:
+  - Fetching the route action (controller, method) via Reflection (along with their corresponding docblocks). These are used in the remaining stages below.
+  - Determining and obtaining info on body parameters, query parameters and headers to be added to the route's documentation.
+  - Obtaining a sample response.
+- The generate command uses information from these parsed routes and other configuration to generate a Markdown file via Blade templating.
+- This Markdown file is passed to Documentarian, which transforms it into HTML, CSS and JavaScript assets.
+- If enabled, a Postman collection is generated as well.

docs/documenting.md

@@ -84,7 +84,8 @@ They will be included in the generated documentation text and example requests.
 
 ![](body_params.png)
 
-Note: a random value will be used as the value of each parameter in the example requests. If you'd like to specify an example value, you can do so by adding `Example: your-example` to the end of your description. For instance:
+### Example parameters
+For each parameter in your request, this package will generate a random value to be used in the example requests. If you'd like to specify an example value, you can do so by adding `Example: your-example` to the end of your description. For instance:
 
 ```php
     /**
@@ -97,7 +98,7 @@ Note: a random value will be used as the value of each parameter in the example
      */
 ```
 
-Note: To exclude a particular parameter from the generated examples (for all languages), you can annotate it with `No-example`. For instance:
+You can also exclude a particular parameter from the generated examples (for all languages) by annotating it with `No-example`. For instance:
 ```php
        /**
         * @queryParam location_id required The id of the location. Example: 1

docs/generating-documentation.md

@@ -51,8 +51,8 @@ php artisan apidoc:rebuild
     - `methods`: an array of the HTTP methods for that route
     - `boundUri`: the complete URL for the route, with any url parameters replaced (/users/{id} -> /users/1)
     - `headers`: key-value array of headers to be sent with route (according to your configuration)
-    - `cleanQueryParameters`: key-value array of query parameters (with example values) to be sent with the request
-    - `cleanBodyParameters`: key-value array of body parameters (with example values) to be sent with the request
+    - `cleanQueryParameters`: key-value array of query parameters with example values to be sent with the request. Parameters which have been excluded from the example requests (see [Example Parameters](documenting.html#example-parameters)) will not be present here.
+    - `cleanBodyParameters`: key-value array of body parameters with example values to be sent with the request. Parameters which have been excluded from the example requests (see [Example Parameters](documenting.html#example-parameters)) will not be present here.
 
 - Add the language to the `example_languages` array in the package config.
 

docs/index.md

@@ -9,6 +9,7 @@ Automatically generate your API documentation from your existing Laravel/Lumen/[
 * [Configuration](config.md)
 * [Generating Documentation](generating-documentation.md)
 * [Documenting Your API](documenting.md)
+* [Internal Architecture](architecture.md)
 
 ## Installation
 > Note: PHP 7 and Laravel 5.5 or higher are required.