docs: add documentation for Swift renderer and improve documentation structure

2024-11-29 18:15:30 +01:00
parent 5c6ecfd638
commit 25058c4703
6 changed files with 226 additions and 43 deletions
@@ -1,6 +1,6 @@
-# Optolith TypeScript to JSON Schema and Markdown
+# Optolith TypeScript Data Model Compiler and Documentation Generator

-This tool provides an opinionated solution for generating **both JSON Schemas and corresponding Markdown documentation** from a set of TypeScript files. The tool does not support all types possible in TypeScript, only those that are needed in [Optolith](https://github.com/elyukai/optolith-client) and that can be represented in a JSON Schema as well.
+This tool provides an opinionated solution for generating **type definitions for multiple targets as well as Markdown documentation** from a set of TypeScript files. The tool does not support all types possible in TypeScript, only those that are needed in [Optolith](https://github.com/elyukai/optolith-client) and that can be represented in a JSON Schema as well.

 ## Why?

@@ -10,6 +10,14 @@ The main issue for JSON Schema with the existing solutions is that the converter

 The main issue for Markdown with the existing solutions is that if you convert from TypeScript, they usually target developers, and if you convert from Markdown, the output has a lot of files or does not support the full JSON Schema feature set.

+## Targets
+
+The following targets are currently supported:
+
+- [JSON Schema](./docs/targets/jsonSchema.md)
+- [Markdown](./docs/targets/markdown.md)
+- [Swift](./docs/targets/swift.md)
+
 ## Installation

 ```sh
@@ -33,7 +41,7 @@ generate({
  outputs: [
    {
      targetDir: join(root, "schema"),
-      renderer: jsonSchema({ spec: jsonSchemaSpec })
+      renderer: jsonSchema({ spec: "Draft_07" })
    },
    {
      targetDir: join(root, "docs", "reference"),
@@ -90,44 +98,30 @@ export default {
 }
 ```

-### Main type
+### Supported JSDoc Tags

-A module comment may indicate the main type of the module, which can be used by directly importing the JSON Schema without the need to specify the definition inside. The type is referenced to by its name.
-
-Example:
-
-```ts
-/**
- * @main Attribute
- */
-```
-
-If no `@main` attribute is present, a default export is used as a fallback.
-
-### Supported JSDoc features
-
-JSDoc | TypeScript | Tag Comment Type | JSON Schema | Markdown
-:-- | :-- | :-- | :-- | :--
-Description | all | `markdown` | `description` keyword | Description
-`@title` | all | `string` | `title` keyword | Heading
-`@markdown` | `string` | `boolean` | — | Type: Markdown-formatted text
-`@minLength` | `string` | `number` | `minLength` keyword | Minimum Length
-`@maxLength` | `string` | `number` | `maxLength` keyword | Maximum Length
-`@pattern` | `string` | `string` | `pattern` keyword | Pattern
-`@format` | `string` | `string` | `format` keyword | Format
-`@integer` | `number` | `boolean` | `"type": "integer"` instead of `"type": "number"` | Type: Integer
-`@minimum` | `number` | `number` | `minimum` keyword | Minimum
-`@maximum` | `number` | `number` | `maximum` keyword | Maximum
-`@exclusiveMinimum` | `number` | `number` | `exclusiveMinimum` keyword | Exclusive Minimum
-`@exclusiveMaximum` | `number` | `number` | `exclusiveMaximum` keyword | Exclusive Maximum
-`@multipleOf` | `number` | `number` | `multipleOf` keyword | Multiple of
-`@minItems` | `array` | `number` | `minItems` keyword | Minimum Items
-`@maxItems` | `array` | `number` | `maxItems` keyword | Maximum Items
-`@uniqueItems` | `array` | `boolean` | `uniqueItems` keyword | Unique Items
-`@minProperties` | `object` | `number` | `minProperties` keyword | Minimum Properties
-`@maxProperties` | `object` | `number` | `maxProperties` keyword | Maximum Properties
-`@patternProperties` | `object` | `string` | `patternProperties` keyword | Values matching pattern
-`readonly` modifier | property | `boolean` | `readOnly` keyword | Read-only property
+JSDoc Tag | Attachable to | Tag Comment Type
+:-- | :-- | :--
+`@title` | all | `string`
+`@default` | all | `any`
+`@deprecated` | all | `boolean \| string`
+`@markdown` | `string` | `boolean`
+`@minLength` | `string` | `number`
+`@maxLength` | `string` | `number`
+`@pattern` | `string` | `string`
+`@format` | `string` | `string`
+`@integer` | `number` | `boolean`
+`@minimum` | `number` | `number`
+`@maximum` | `number` | `number`
+`@exclusiveMinimum` | `number` | `number`
+`@exclusiveMaximum` | `number` | `number`
+`@multipleOf` | `number` | `number`
+`@minItems` | `array` | `number`
+`@maxItems` | `array` | `number`
+`@uniqueItems` | `array` | `boolean`
+`@minProperties` | `object` | `number`
+`@maxProperties` | `object` | `number`
+`@patternProperties` | `object` | `string`

 #### Boolean tags

@@ -155,7 +149,7 @@ type Dictionary = {

 Generics are supported, but some export formats may not be able to support them, such as JSON Schema. You can use the `resolveTypeParameters` for a `Renderer` to receive an AST without type parameters. Types with type parameters are still present if all of their type parameters have default arguments, which replace all type parameter occurrences in the type definition. The AST type is the same, but you can ignore all type argument and type parameter properties, since they are all `undefined`.

-## Defining your own renderer
+## Defining your own target

 If you want to write your own renderer, you must provide a value that conforms to the `Renderer` type. This type consists of three parts. An AST transformer function, a file extension and (optionally) whether to resolve type parameters (see section about generics).

@@ -0,0 +1,59 @@
+# JSON Schema
+
+Generates a JSON Schema document for every source file. JSDoc comments are used to provide additional information for JSON Schemas.
+
+## Options
+
+Options are provided as an object to the renderer function.
+
+- `allowAdditionalProperties`
+  - **Description:** Whether to allow unresolved additional keys in object definitions. This sets the `additionalProperties` JSON Schema keyword for all applicable types.
+  - **Required:** no
+  - **Type:** `boolean`
+  - **Default:** `false`
+- `spec`
+  - **Description:** The JSON Schema specification to use.
+  - **Required:** no
+  - **Type:** `JsonSchemaSpec`
+  - **Default:** `"Draft_2020_12"`
+
+## Main type
+
+A module comment may indicate the main type of the module, which can be used by directly importing the JSON Schema without the need to specify the definition inside. The type is referenced to by its name.
+
+Example:
+
+```ts
+/**
+ * @main Attribute
+ */
+```
+
+If no `@main` attribute is present, a default export is used as a fallback.
+
+## Supported JSDoc features
+
+JSDoc | JSON Schema
+:-- | :--
+Description | `description` keyword
+`@title` | `title` keyword
+`@default` | `default` keyword
+`@deprecated` | `deprecated` keyword (since `"Draft_2019_09"`)
+`@markdown` | —
+`@minLength` | `minLength` keyword
+`@maxLength` | `maxLength` keyword
+`@pattern` | `pattern` keyword
+`@format` | `format` keyword
+`@integer` | `"type": "integer"` instead of `"type": "number"`
+`@minimum` | `minimum` keyword
+`@maximum` | `maximum` keyword
+`@exclusiveMinimum` | `exclusiveMinimum` keyword
+`@exclusiveMaximum` | `exclusiveMaximum` keyword
+`@multipleOf` | `multipleOf` keyword
+`@minItems` | `minItems` keyword
+`@maxItems` | `maxItems` keyword
+`@uniqueItems` | `uniqueItems` keyword
+`@minProperties` | `minProperties` keyword
+`@maxProperties` | `maxProperties` keyword
+`@patternProperties` | `patternProperties` keyword
+`readonly` modifier | `readOnly` keyword
@@ -0,0 +1,34 @@
+# Markdown
+
+Generates a Markdown file for every source file, containing documentation for defined types generated from documentation comments as well as the type definitions themselves.
+
+## Options
+
+The Markdown renderer currently has no options.
+
+## Supported JSDoc features
+
+JSDoc | Markdown
+:-- | :--
+Description | Description
+`@title` | Heading
+`@default` | Default
+`@deprecated` | Deprecated
+`@markdown` | Type: Markdown-formatted text
+`@minLength` | Minimum Length
+`@maxLength` | Maximum Length
+`@pattern` | Pattern
+`@format` | Format
+`@integer` | Type: Integer
+`@minimum` | Minimum
+`@maximum` | Maximum
+`@exclusiveMinimum` | Exclusive Minimum
+`@exclusiveMaximum` | Exclusive Maximum
+`@multipleOf` | Multiple of
+`@minItems` | Minimum Items
+`@maxItems` | Maximum Items
+`@uniqueItems` | Unique Items
+`@minProperties` | Minimum Properties
+`@maxProperties` | Maximum Properties
+`@patternProperties` | Values matching pattern
+`readonly` modifier | Read-only property
@@ -0,0 +1,96 @@
+# Swift
+
+Generates a Swift file for every source file, creating types and optionally initializers and decoders for the corresponding JSON structures.
+
+## Options
+
+Options are provided as an object to the renderer function.
+
+- `addConformances`
+  - **Description:** Conformances to add to generated types.
+  - **Required:** no
+  - **Type:** `ConformanceOptions[]`
+  - **Default:** `[]`
+- `convertIdentifiersToNamingConvention`
+  - **Description:** If generated type and member names’ casing should be converted to Swift conventions.
+  - **Required:** no
+  - **Type:** `boolean`
+  - **Default:** `false`
+- `decodableSynthesization`
+  - **Description:** If generated `struct` types should have `Decodable` conformances.
+  - **Required:** no
+  - **Type:** `DecodableSynthesizationOptions`
+  - **Default:** `undefined`
+- `defaultPublic`
+  - **Description:** If generated types and members should be `public`.
+  - **Required:** no
+  - **Type:** `boolean`
+  - **Default:** `false`
+- `forceConstantStructMembers`
+  - **Description:** If `struct` members are always generated as `let`. This ignores the `isReadOnly` AST flag.
+  - **Required:** no
+  - **Type:** `boolean`
+  - **Default:** `false`
+- `generateStructInitializers`
+  - **Description:** If generated `struct` types should have initializers generated. Initializers will have default `nil` values for optional members.
+  - **Required:** no
+  - **Type:** `boolean`
+  - **Default:** `false`
+- `packageName`
+  - **Description:** The package name to use in all file comments.
+  - **Required:** yes
+  - **Type:** `string`
+  - **Default:** —
+
+### `DecodableSynthesizationOptions`
+
+- `discriminatorKey`
+  - **Description:** For enumerations with associated values, the key of the discriminator property.
+  - **Required:** yes
+  - **Type:** `string`
+  - **Default:** —
+
+### `ConformanceOptions`
+
+- `identifier`
+  - **Description:** The identifier of the type to add.
+  - **Required:** yes
+  - **Type:** `string | (( node: RecordNode | UnionNode | EnumerationNode | TypeParameterNode ) => string)`
+  - **Default:** —
+- `includesDecodable`
+  - **Description:** If the type includes `Decodable` conformance, which will not add an additional `Decodable` conformance if `decodableSynthesization` is used.
+  - **Required:** no
+  - **Type:** `boolean`
+  - **Default:** `false`
+- `forMainTypes`
+  - **Description:** If set, whether the type is only for main types (`true`) or sub types (`false`).
+  - **Required:** no
+  - **Type:** `boolean`
+  - **Default:** `undefined`
+
+## Supported JSDoc features
+
+JSDoc | Swift
+:-- | :--
+Description | Documentation comment
+`@title` | —
+`@default` | —
+`@deprecated` | Deprecation annotation
+`@markdown` | —
+`@minLength` | —
+`@maxLength` | —
+`@pattern` | —
+`@format` | —
+`@integer` | Type: `Int`
+`@minimum` | —
+`@maximum` | —
+`@exclusiveMinimum` | —
+`@exclusiveMaximum` | —
+`@multipleOf` | —
+`@minItems` | —
+`@maxItems` | —
+`@uniqueItems` | —
+`@minProperties` | —
+`@maxProperties` | —
+`@patternProperties` | —
+`readonly` modifier | `let` variable member
@@ -30,7 +30,7 @@ export type JsonSchemaRendererOptions = {
  spec?: JsonSchemaSpec

  /**
-   * Whether to allow unresolved additional keys in object definitions.
+   * Whether to allow unresolved additional keys in object definitions. This sets the `additionalProperties` JSON Schema keyword for all applicable types.
   * @default false
   */
  allowAdditionalProperties?: boolean
@@ -59,7 +59,7 @@ export type SwiftOptions = {
  convertIdentifiersToNamingConvention?: boolean

  /**
-   * if generated `struct` types should have initializers generated. Initializers will have default `nil` values for optional members.
+   * If generated `struct` types should have initializers generated. Initializers will have default `nil` values for optional members.
   */
  generateStructInitializers?: boolean