docs: improve documentation (#272)

Co-authored-by: Maciej Urbańczyk <[email protected]>

README.md

@@ -73,7 +73,7 @@ The generation process uses the predefined `CommonModel`s from the input stage t
 
 Check out [the example](#example) to see how to use the library and [generators document](./docs/generators.md) for more info.
 
-> **NOTE**: Each implemented language has different options, dictated by the nature of the language. Keep this in mind when selecting a language.
+> **NOTE**: Each implemented language has different options, dictated by the nature of the language.
 
 ## Example
 

docs/development.md

@@ -1,15 +1,16 @@
 # Development guideline
+These are some of the development guidelines and help to setup the library for development.
 
 ## Environment setup
-Here is how to setup the development environment:
+To setup the environment follow these steps:
 1. Setup the project by first installing the dependencies `npm install`
-2. Write code and tests
-3. Make sure all tests pass `npm test`
-4. Make sure code is well formatted and secure `npm run lint`
+1. Make sure the tests pass by running `npm run test` script
+    - [blackbox testing](#blackbox-testing) are excluded when running the `test` script because it require some extra setup.
+1. Make sure code is well formatted and secure `npm run lint`
 
 ## Blackbox testing
 The blackbox testing have some different requirements in order to successfully run:
 - To to run the `java` blackbox tests, you need to have JDK installed.
-- To to run the `ts` blackbox tests, you need to have TypeScript installed `npm install -g typescript`.
+- To to run the `ts` blackbox tests, you need to have TypeScript installed globally - `npm install -g typescript`.
 
-By default the blackbox tests are not run with the regular `npm run test`, but can be run with `npm run test:blackbox`.
+By default the blackbox tests are not run with the regular `npm run test`, but can be run with `npm run test:blackbox`.

docs/input_processing.md

@@ -1,32 +1,19 @@
-As of now two inputs are supported:
-- JSON Schema Draft 7
-- AsyncAPI version 2.0.0
+# Input process
 
-## Internal model representation
+The [InputProcessor](../src/processors/InputProcessor.ts) is our main point of entry for processing input data. It uses the defined input processors (`AsyncAPIInputProcessor`, `JsonSchemaInputProcessor`, ...) by first calling `shouldProcess` function for each input processor to figure out if the input data should be processed by the respective processor. If it should the `process` function is then called. It uses a first-come, first-serve principle, where the first processor that accepts the input process's it. If no processor accepts the input it defaults to `JsonSchemaInputProcessor`. 
 
-![Class diagram](./assets/class_diagram.png)
+The `process` function are expected to return `CommonInputModel` which is a wrapper for the core data representation of `CommonModel`. This is done to ensure we can return multiple models for any input to allow for references, inheritance etc. 
 
-As seen on the class diagram the `InputProcessor` is our main point of entry for processing input data. 
-
-It uses the defined input processors (`AsyncAPIInputProcessor`, `JsonSchemaInputProcessor`, ...) by first calling `shouldProcess` function of each and if the function returns true it calls the `process` function. 
-
-If no processes returns true it defaults to `JsonSchemaInputProcessor`. 
-
-The `process` function are expected to return `CommonInputModel` which is a wrapper for the core data representation of `CommonModel`. 
-
-This is done to ensure we can return multiple models for any input to allow for references, inheritance etc. 
-
-As said the core internal representation of a data model is `CommonModel`. This contains the data definition by using known keywords from JSON Schema, but instead of it representing a validation rules it represent data definition. The explanation for the `CommonModel` properties can be found [here](../API.md#CommonModel).
+As said the core internal representation of a data model is `CommonModel`. It contains the data definition by using known keywords from JSON Schema, but instead of it representing a validation rules it represents the data definition for the model. The explanation for the `CommonModel` properties can be found [here](../API.md#CommonModel).
 
 ## AsyncAPI
-At the moment the library only supports the whole AsyncAPI file as input where it generates models for all defined message payloads. If any other kind of AsyncAPI input is wanted please create a [feature request](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)!
+At the moment the library only supports the whole AsyncAPI file as input where it generates models for all defined message payloads. If any other kind of AsyncAPI input is wanted please create a [feature request](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md).
 
 The AsyncAPI input processor expects that the property `asyncapi` is defined in order to know it should be processed using this.
 
 The payload, since it is of type JSON Schema, is then passed to the [JSON Schema processor](#JSON-Schema) which handle the rest of the processing.
 
-
 ## JSON Schema
 For us to convert JSON Schema into `CommonInputModel` we use a process we call the interpreter process. This means that we interpret the JSON Schema validation rules (`Schema` or Boolean) into data definitions (`CommonModel`). This process is quite complex and needs it own section for explaining how it works.
 
-Read [this](./docs/interpretation_of_JSON_Schema_draft_7.md) document for more information.
+Read [this](./interpretation_of_JSON_Schema_draft_7.md) document for more information.

docs/interpretation_of_JSON_Schema_draft_7.md

@@ -4,7 +4,7 @@ The library transforms JSON Schema from data validation rules to data definition
 
 The algorithm tries to get to a model whose data can be validated against the JSON schema document. 
 
-We only provide the underlying structure of the schema file for the model, where constraints/annotations such as `maxItems`, `uniqueItems`, `multipleOf`, etc, are not transformed.
+As of now we only provide the underlying structure of the schema file for the model, where constraints/annotations such as `maxItems`, `uniqueItems`, `multipleOf`, etc. are not interpreted.
 
 ## Interpreter 
 The main functionality is located in the `Interpreter` class. This class ensures to recursively create (or retrieve from a cache) a `CommonModel` representation of a Schema. We have tried to keep the functionality split out into separate functions to reduce complexity and ensure it is easy to maintain. 

src/models/CommonModel.ts

@@ -12,6 +12,7 @@ import { Schema } from './Schema';
  * @property {CommonModel | CommonModel[]} items defines the type for `array` models as `CommonModel`.
  * @property {Record<string, CommonModel>} properties defines the properties and its expected types as `CommonModel`.
  * @property {CommonModel} additionalProperties are used to define if any extra properties are allowed, also defined as a  `CommonModel`.
+ * @property {Record<string, CommonModel>} patternProperties are used for any extra properties that matches a specific pattern to be of specific type.
  * @property {string} $ref is a reference to another `CommonModel` by using`$id` as a simple string.
  * @property {string[]} required list of required properties.
  * @property {string[]} extend list of other `CommonModel`s this model extends, is an array of `$id` strings.