JSON Schema -> Typescript concatenates all descriptions in JSDoc

[Fleker]

I have been looking at this issue for a few days, where our reference docs for a few objects end up extremely verbose, eg.

/**
 * 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:

{
  "$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:

/**
 * 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.

[Fleker]

This might be similar to #1582 but seemed like a separate issue.