From 60d71e4c7ec8ded92e4492a36017344639e5b9b3 Mon Sep 17 00:00:00 2001 From: Jonas Lagoni Date: Thu, 25 Apr 2024 11:22:03 +0200 Subject: [PATCH] docs: remove outdated generator docs (#1951) --- docs/README.md | 3 - docs/generators.md | 167 ----------------------------------- docs/languages/TypeScript.md | 6 +- docs/usage.md | 2 +- package.json | 2 +- 5 files changed, 5 insertions(+), 175 deletions(-) delete mode 100644 docs/generators.md diff --git a/docs/README.md b/docs/README.md index 5b194699bd..e8ea62a1dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,9 +42,6 @@ Contains many advanced ways to integrate Modelina _(i.e. websites)_. ### [Development](./development.md) Explains how to setup the project for development. -### [Generators](./generators.md) -Details which different generator options are supported. - ### [Presets](./presets.md) Goes more in-depth into how the preset system works, which enables full customization of generators. diff --git a/docs/generators.md b/docs/generators.md deleted file mode 100644 index 71c7029523..0000000000 --- a/docs/generators.md +++ /dev/null @@ -1,167 +0,0 @@ -# Generators - - - - - -- [Generator's options](#generators-options) - * [TypeScript](#typescript) - + [Generator options](#generator-options) - + [Render complete model options](#render-complete-model-options) - * [Java](#java) - + [Generator options](#generator-options-1) - + [Render complete model options](#render-complete-model-options-1) - * [JavaScript](#javascript) - + [Generator options](#generator-options-2) - + [Render complete model options](#render-complete-model-options-2) - * [Go](#go) - + [Generator options](#generator-options-3) - + [Render complete model options](#render-complete-model-options-3) - * [C#](#c%23) - + [Generator options](#generator-options-4) - + [Render complete model options](#render-complete-model-options-4) -- [Custom generator](#custom-generator) - - - -**Generators** are classes that are used to render models for a given language. - -## Generator's options - -For Modelina, there exist 3 types of options for the generation process. -1. Default options, are the default options the rest overwrite. -2. Generator options, are used as the baseline that is by default used for each model render. -3. Render options, are the last resort to specialize options for the individual rendering of a model, that overwrite the generator options. - -Generator options are passed as the first argument to the generator's constructor. Check the example: - -```ts -const generator = new TypeScriptGenerator({ ...options }); -``` - -Render options are passed as the first argument to the generator's render function. Check the example: - -```ts -const generator = ... -const model = ... -const inputModel = ... -generator.render(model, inputModel, { ...options }); -``` - -Default generator options (common to all generators) are as follows: - -| Option | Type | Description | Default value | -|---|---|---|---| -| `indentation` | Object | Options for indentation ([example](../examples/indentation-type-and-size)). | - | -| `indentation.type` | String | Type of indentation. Its value can be either `SPACES` or `TABS` and are typed by `IndentationTypes`| `SPACES` | -| `indentation.size` | String | Size of indentation. | 2 | -| `defaultPreset` | Object | Default preset for generator. For more information, read [customization](./presets.md) document. | _Implemented by generator_ | -| `presets` | Array | Array contains **presets**. For more information, read [customization](./presets.md) document. | `[]` | - -In addition, generators take additional options when calling their `renderCompleteModel(input, options)` functions. -This allows the caller to specify additional options when generating a multi-file model from the input with cross dependencies. - -Below is a list of additional options available for a given generator. - -### [TypeScript](./languages/TypeScript.md) - -#### Generator options - -| Option | Type | Description | Default value | -|---|---|---|---| -| `renderTypes` | Boolean | Render signature for types. | `true` | -| `mapType` | String | It indicates which mapping type should be rendered for the `object` type. Its value can be one of `map`, `record` or `indexedObject`. | `map` | -| `modelType` | String | It indicates which model type should be rendered for the `object` type. Its value can be either `interface` or `class`. | `class` | -| `enumType` | String | It indicates which type should be rendered for the `enum` type. Its value can be either `union` or `enum`. | `enum` | -| `namingConvention` | Object | Options for naming conventions. | - | -| `namingConvention.type` | Function | A function that returns the format of the type. | _Returns pascal cased name, and ensures that reserved keywords are never rendered__ | -| `namingConvention.property` | Function | A function that returns the format of the property. | _Returns camel cased name, and ensures that names of properties does not clash against reserved keywords for TS, as well as JS to ensure painless transpilation_ | - -#### Render complete model options - -| Option | Type | Description | Default value | -|----------------|--------------------------|----------------------------------------------------------------------------|---------------| -| `moduleSystem` | 'ESM' | 'CJS' | Which module system the generated files should use (`import` or `require`) | 'CJS' | -| `exportType` | 'default' | 'named' | Whether the exports should be default or named exports | 'default' | - -### [Java](./languages/Java.md) - -#### Generator options - -| Option | Type | Description | Default value | -|---|---|---|---| -| `collectionType` | String | It indicates with which signature should be rendered the `array` type. Its value can be either `List` (`List<{type}>`) or `Array` (`{type}[]`). | `List` | -| `namingConvention` | Object | Options for naming conventions. | - | -| `namingConvention.type` | Function | A function that returns the format of the type. | _Returns pascal cased name, and ensures that reserved keywords are never rendered__ | -| `namingConvention.property` | Function | A function that returns the format of the property. | _Returns camel cased name, and ensures that names of properties does not clash against reserved keywords_ | - -#### Render complete model options - -| Option | Type | Description | Default value | -|---------------|--------|-----------------------------------------------|---------------| -| `packageName` | string | The package name to generate the models under | [required] | - -### [JavaScript](./languages/JavaScript.md) - -#### Generator options - -| Option | Type | Description | Default value | -|---|---|---|---| -| `namingConvention` | Object | Options for naming conventions. | - | -| `namingConvention.type` | Function | A function that returns the format of the type. | _Returns pascal cased name, and ensures that reserved keywords are never rendered_ | -| `namingConvention.property` | Function | A function that returns the format of the property. | _Returns camel cased name, and ensures that names of properties does not clash against reserved keywords_ | - -#### Render complete model options - -| Option | Type | Description | Default value | -|----------------|--------------------------|----------------------------------------------------------------------------|---------------| -| `moduleSystem` | 'ESM' | 'CJS' | Which module system the generated files should use (`import` or `require`) | 'CJS' | - -### [Go](./languages/Go.md) - -#### Generator options - -| Option | Type | Description | Default value | -|---|---|---|---| -| `namingConvention` | Object | Options for naming conventions. | - | -| `namingConvention.type` | Function | A function that returns the format of the type. | _Returns pascal cased name_ | -| `namingConvention.field` | Function | A function that returns the format of the field. | _Returns pascal cased name_ | - -#### Render complete model options - -| Option | Type | Description | Default value | -|---------------|--------|-----------------------------------------------|---------------| -| `packageName` | string | The package name to generate the models under | [required] | - -### [C#](./languages/Csharp.md) - -#### Generator options - -| Option | Type | Description | Default value | -|---|---|---|---| -| `namingConvention` | Object | Options for naming conventions. | - | -| `namingConvention.type` | Function | A function that returns the format of the type. | _Returns pascal cased name, and ensures that reserved keywords are never rendered__ | -| `namingConvention.property` | Function | A function that returns the format of the property. | _Returns camel cased name, and ensures that names of properties does not clash against reserved keywords_ | - -#### Render complete model options - -| Option | Type | Description | Default value | -|-------------|--------|--------------------------------------------|---------------| -| `namespace` | string | The namespace to generate the models under | [required] | - -## Custom generator - -The minimum set of required actions to create a new generator are: - -- Source code must be included in [generators](../src/generators) folder. -- Must extend the abstract [`AbstractGenerator`](../src/generators/AbstractGenerator.ts) class, -- Must define [`Preset`](./customization.md)'s shape for the language, -- Must define language options by passing an interface describing additional options to the first generic argument of [`AbstractGenerator`](../src/generators/AbstractGenerator.ts). The interface must also be extended by `CommonGeneratorOptions` interface, -- Must define default options as static class's field, which must be extended by `defaultGeneratorOptions`, -- Default options must include `defaultPreset` property, -- Must implement `render` function, -- Must define **Renderers** classes for available model types in a given language. **Renderer** is an instance of the class with common helper functions to render appropriate model type and must be extended by [`AbstractRenderer`](../src/generators/AbstractRenderer.ts) class - [example](../src/generators/typescript/renderers/ClassRenderer.ts). - -Check the [generator implementation](../src/generators/typescript/TypeScriptGenerator.ts) for `TypeScript` language to see how it should look like. - -If you created a generator then you can contribute it to the AsyncAPI Model SDK and it will become the official supported generator. diff --git a/docs/languages/TypeScript.md b/docs/languages/TypeScript.md index 68f82494be..b72b2d84cc 100644 --- a/docs/languages/TypeScript.md +++ b/docs/languages/TypeScript.md @@ -24,13 +24,13 @@ There are special use-cases that each language supports; this document pertains ## Generate an interface instead of classes -Sometimes you don't care about classes, but rather have interfaces generated. This can be changed through the [modelType configuration](https://github.com/asyncapi/modelina/blob/master/docs/generators.md#typescript). +Sometimes you don't care about classes, but rather have interfaces generated. This can be changed through the `modelType` configuration Check out this [example out for a live demonstration](../../examples/typescript-interface). ## Generate different `mapType`s for an `object` -Typescript offers different `mapType`s which can simplify the use based on the needs. This behavior can be changed through the [`mapType` configuration](https://github.com/asyncapi/modelina/blob/master/docs/generators.md#typescript). +Typescript offers different `mapType`s which can simplify the use based on the needs. This behavior can be changed through the `mapType` configuration. - Use `map` when you need a dynamic collection of key-value pairs with built-in methods for manipulation. - Use `record` when you want to define an object with specific keys and their corresponding value types. @@ -53,7 +53,7 @@ Also, check out this [example for a live demonstration](../../examples/typescrip ## Generate union types instead of enums -Typescript offers union types which can simplify the use as no keywords are needed and the values can be set directly. This behavior can be changed through the [modelType configuration](https://github.com/asyncapi/modelina/blob/master/docs/generators.md#typescript). An example of the generated code can be seen below: +Typescript offers union types which can simplify the use as no keywords are needed and the values can be set directly. This behavior can be changed through the `modelType` configuration. An example of the generated code can be seen below: ```ts // enumType = 'enum' diff --git a/docs/usage.md b/docs/usage.md index 61ac2f3a0f..c0b710a6de 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -64,7 +64,7 @@ generator.render(model, inputModel, { ...options }); The output format is designed for you to use the generated models in further contexts. It might be part of a larger code generation such as AsyncAPI templates. This means that you can glue multiple models together into one large file, or split it out as you see fit. -All [generate functions](./generators.md) return an array of `OutputModel`s, which contains the following properties. +All `generate` functions return an array of `OutputModel`s, which contains the following properties. | Property | Type | Description | |---|---|---| diff --git a/package.json b/package.json index c22103048c..4b122194eb 100644 --- a/package.json +++ b/package.json @@ -127,7 +127,7 @@ "lint:modelina": "eslint --max-warnings 0 --config .eslintrc .", "lint:cli": "cd modelina-cli && npm run lint", "lint:fix": "eslint --max-warnings 0 --config .eslintrc . --fix", - "generate:readme:toc": "markdown-toc -i README.md && markdown-toc -i ./docs/other-tools.md && markdown-toc -i ./docs/languages/Scala.md && markdown-toc -i ./docs/languages/Php.md && markdown-toc -i ./docs/languages/Cplusplus.md && markdown-toc -i ./examples/README.md && markdown-toc -i ./docs/languages/Python.md && markdown-toc -i ./docs/usage.md && markdown-toc -i ./docs/integration.md && markdown-toc -i ./docs/advanced.md && markdown-toc -i ./docs/languages/Dart.md && markdown-toc -i ./docs/languages/TypeScript.md && markdown-toc -i ./docs/languages/Java.md && markdown-toc -i ./docs/languages/JavaScript.md && markdown-toc -i ./docs/languages/Csharp.md && markdown-toc -i ./docs/README.md && markdown-toc -i ./docs/generators.md && markdown-toc -i ./docs/presets.md", + "generate:readme:toc": "markdown-toc -i README.md && markdown-toc -i ./docs/other-tools.md && markdown-toc -i ./docs/languages/Scala.md && markdown-toc -i ./docs/languages/Php.md && markdown-toc -i ./docs/languages/Cplusplus.md && markdown-toc -i ./examples/README.md && markdown-toc -i ./docs/languages/Python.md && markdown-toc -i ./docs/usage.md && markdown-toc -i ./docs/integration.md && markdown-toc -i ./docs/advanced.md && markdown-toc -i ./docs/languages/Dart.md && markdown-toc -i ./docs/languages/TypeScript.md && markdown-toc -i ./docs/languages/Java.md && markdown-toc -i ./docs/languages/JavaScript.md && markdown-toc -i ./docs/languages/Csharp.md && markdown-toc -i ./docs/README.md && markdown-toc -i ./docs/presets.md", "generate:assets": "npm run generate:assets:modelina && npm run generate:assets:cli", "generate:assets:modelina": "npm run build:prod && npm run docs && npm run generate:readme:toc && npm run format", "generate:assets:cli": "cd modelina-cli && npm run generate:assets",