docs: improve docs (#163)

README.md

@@ -40,7 +40,7 @@ const { outputPath } = await openapiToTsJsonSchema({
 });
 ```
 
-...then use them in your code:
+...and use them in your TS project:
 
 ```ts
 import Ajv from 'ajv';
@@ -62,19 +62,27 @@ const valid = ajv.validate(myGeneratedModelSchema, myModel);
 | ---------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
 | **openApiSchema** _(required)_                 | `string`                                   | Path to the OpenApi file (supports yaml and json).                                                                                                           | -          |
 | **definitionPathsToGenerateFrom** _(required)_ | `string[]`                                 | OpenApi definition object paths to generate the JSON schemas from. Only matching paths will be generated. (Supports dot notation: `["components.schemas"]`). | -          |
-| **refHandling**                                | `"inline" \| "import" \| "keep"`           | `"inline"`: inline `$ref` schemas. <br/>`"import"`: generate and import `$ref` schemas.<br/>`"keep"`: keep `$ref` value.                                     | `"inline"` |
+| **refHandling**                                | `"inline" \| "import" \| "keep"`           | `"inline"`: inline `$ref` schemas. <br/>`"import"`: generate and import `$ref` schemas.<br/>`"keep"`: keep `$ref` values.                                    | `"inline"` |
 | **schemaPatcher**                              | `(params: { schema: JSONSchema }) => void` | Dynamically patch generated JSON schemas. The provided function will be invoked against every single JSON schema node.                                       | -          |
 | **outputPath**                                 | `string`                                   | Path where the generated schemas will be saved. Defaults to `/schemas-autogenerated` in same directory as provided `openApiSchema`.                          | -          |
 | **plugins**                                    | `ReturnType<Plugin>[]`                     | A set of optional plugin to generate any extra custom. See [plugins docs](./docs/plugins.md). output.                                                        | -          |
 | **silent**                                     | `boolean`                                  | Don't `console.log` user messages.                                                                                                                           | `false`    |
 
-### Notes
+## Notes
 
-Generated TypeScript JSON schema path names get escaped in order to be valid file system names.
+Take a look at the [Developer's notes](./docs/developer-notes.md) for a few more in-depth explanations.
 
-Circular `$ref`s can be technically resolved with "import" `refHandling` option. But TS will stop the type recursion and type the schema as `any` (error `ts(7022)`). See [relevant tests](https://github.com/toomuchdesign/openapi-ts-json-schema/blob/master/test/circularReference.test.ts).
+### `$ref`s handling
 
-Take a look at the [Developer's notes](./docs/developer-notes.md) for a few more in-depth explanations.
+`openapi-ts-json-schema` provides 3 different strategies to handle OpenApi `$ref` properties configurable via the `refHandling` option:
+
+- `inline`: `$ref` values get recursively replaced with inline copies of the target definition. This produces self-contained standalone schemas with usually repeated inline definitions
+- `import`: `$ref` values get replaced with a local variable pointing to module of the generated target definition
+- `keep`: `$ref` values get preserved.
+
+### Circular `$ref`s
+
+Circular `$ref`s can be technically resolved with "import" `refHandling` option. However, TS engine will interrupt type recursion and type the schema as `any` (error `ts(7022)`). See [relevant tests](https://github.com/toomuchdesign/openapi-ts-json-schema/blob/master/test/circularReference.test.ts).
 
 ## Return values