glideapps / glideapps/quicktype
JSON Schema -> Typescript concatenates all descriptions in JSDoc
- Dominant language
- TypeScript
- Stars
- 13.9k
- Forks
- 1.2k
- Avg merge
- 8h 53m
- Merged PRs (30d)
- 369
Description
I have been looking at this issue for a few days, where our reference docs for a few objects end up extremely verbose, eg.
```typescript
/**
* An image icon.
*
* An image shown in the card.
*
* An image shown in the table.
* etc.
*/
export interface Image {
```
Our JSON schema file provides a description for every field, even when the property points to a `$ref`. This schema file is generated as part of our build process:
```json
{
"$schema": "http://json-schema.org/draft-06/schema#",
"$ref": "#/definitions/Card",
"definitions": {
"Image": {
"description": "An image icon.",
"type": "object",
"properties": {
"url": {
"description": "The source url of the image. Images can be JPG, PNG and GIF (animated and non-animated). Required.",
"type": "string"
},
"alt": {
"description": "A text description of the image to be used for accessibility, e.g. screen readers. Required.",
"type": "string"
},
"height": {
"description": "The height of the image in pixels. Optional.",
"type": "integer",
"format": "int32"
},
"width": {
"description": "The width of the image in pixels. Optional.",
"type": "integer",
"format": "int32"
}
}
},
"Card": {
"description": "A basic card for displaying some information, e.g. an image and_or text.",
"type": "object",
"properties": {
"title": {
"description": "Overall title of the card. Optional.",
"type": "string"
},
"subtitle": {
"description": "Optional.",
"type": "string"
},
"text": {
"description": "Body text of the card. Supports a limited set of markdown syntax for formatting. Required, unless image is present.",
"type": "string"
},
"image": {
"description": "An image in a card",
"$ref": "#/definitions/Image"
},
"imageFill": {
"description": "How the image background will be filled. Optional.",
"type": "string",
"enum": [
"UNSPECIFIED",
"GRAY",
"WHITE",
"CROPPED"
]
},
"button": {
"description": "Button with an outbound link. Optional.",
"type": "object"
}
}
}
}
}
```
Using `quicktype -s schema my-schema.json -o my-service.ts --just-types`:
```typescript
/**
* A basic card for displaying some information, e.g. an image and_or text.
*/
export interface Card {
/**
* Button with an outbound link. Optional.
*/
button?: { [key: string]: any };
/**
* An image in a card
*/
image?: Image;
/**
* How the image background will be filled. Optional.
*/
imageFill?: ImageFill;
/**
* Optional.
*/
subtitle?: string;
/**
* Body text of the card. Supports a limited set of markdown syntax for formatting.
* Required, unless image is present.
*/
text?: string;
/**
* Overall title of the card. Optional.
*/
title?: string;
}
/**
* An image in a card
*
* An image icon.
*/
export interface Image {
/**
* A text description of the image to be used for accessibility, e.g. screen readers.
* Required.
*/
alt?: string;
/**
* The height of the image in pixels. Optional.
*/
height?: number;
/**
* The source url of the image. Images can be JPG, PNG and GIF (animated and non-animated).
* Required.
*/
url?: string;
/**
* The width of the image in pixels. Optional.
*/
width?: number;
}
/**
* How the image background will be filled. Optional.
*/
export enum ImageFill {
Cropped = "CROPPED",
Gray = "GRAY",
Unspecified = "UNSPECIFIED",
White = "WHITE",
}
```
Note how `Image` has multiple descriptions together. This isn't really intended, as only the primary description should. be used there while the contextual one as a property should only appear in the comments for the `Card`.
Contributor guide
Assessment
This issue has not been assessed yet.