n3ps / json-schema-to-jsdoc Goto Github PK

It would be useful if there was support for pattern properties in a schema. Currently, if a property of type "object" uses the "patternProperties" field to represent an object with dynamic properties, the output type is simply "object". For example, given this part of a schema:

"test": {
  "type": "object",
  "patternProperties": {
    ".*": {
      "type": "number"
    }
  }
}

The tool just yields:

/**
 * @prop {object} test
 */

Whereas it would be more useful if it yielded something like:

/**
 * @prop {Object<string, number>} test
 */

For a dynamic property which is of "object" type, such as this:

"test": {
  "type": "object",
  "patternProperties": {
    ".*": {
      "type": "object",
      "properties": {
        "subProp": "string"
      }
    }
  }
}

Although it could end up looking quite messy, it would still be useful if it yielded something like:

/**
 * @prop {Object<string, {subProp: string}>} test
 */

Hi,

Now that existing behavior is fully tested, I'm wondering whether you are open to some breaking changes or if you only may want the following as config changes:

• 1. Avoid auto-adding "Represents a". If the schema doesn't have one, it should be ok to have resulting jsdoc without a description.
• 2. When auto-adding "Represents a", use schema.title instead of schema.id. id was only a standard property in an early draft, and its replacement $id expects a URI. For short plain text, one can use title. I presume this is what was intended here.
• 3. Build a @typedef element instead of @name. @name is used when you are forcing surrounding code to treat an item with that tag. But @typedef is intended for defining types. I'm not sure if people have use cases for @name, but I think in any case @typedef would be a better default, and at least optional.
  • 1. The built @typedef could rely on the schema type for its type portion (and the title for its name), though user config might override (e.g., I like to use "PlainObject" instead of "object" to denote cases where the object is known not to need a special type).
• 4. Avoid building trailing spaces:
  • 1. After @name when there is no schema.title. (A test should in any case be added for when one is present.)
  • 2. Avoid extra trailing space
  • 3. Option to avoid any trailing space and - when there is no schema.description
• 5. Provide an option for descriptions not to add a - at all as some styles do not use a hyphen.
• 6. Ability to disable the capitalized auto-typing of untyped properties (the curly bracketed type could either be omitted or left empty).
• 7. Allow controlling the indent; by default I think it should be one space as in the docs instead of 2 spaces.
• 8. Use schema.default for e.g., @param {MyType} [someName=aDefaultValue].
• 9. For nested properties, avoid prefixing with ., but use the approach documented with @property, i.e., of having the ancestors with their own document, and then the descendants repeating the ancestor info joined by dots e.g., @property {object} grandparent then @property {object} grandparent.parent then @property {someType} grandparent.parent.child.
• 10. Auto-add line breaks and asterisks if the description would cause the line length to go past a certain point, e.g., to build:

 /**
  * @property {string} [aStringProp] - This is a very, very, very, very, very, very, very, very
  * very, very, very long description.
  */

• 11. Also supporting arrays whose items are checked instead of properties.

I think a license copy should be added. The package.json says ISC, so I've been acting under the assumption that that's what it is. (I ask since it is the default of npm init.)

It would be good if there was support for typed arrays. For example, for this schema property:

"arrTest": {
  "type": "array",
  "items": {
    "type": "number"
  }
}

The output would be @property {number[]} arrTest rather than just @property {array} arrTest

The following should be the same

"schema": {
  "type": "string",
  "enum": [
    "test"
  ]
}

"schema": {
  "type": "string",
  "const": "test"
}

But currently the output is different because the const is not supported

@property {"test"} schema

@property {string} schema

With the recent set of changes, the npm package version is ready to be bumped. I propose 1.0.0 since it has considerably more features than my first iteration.

@brettz9 do you have anything else you wanted to include?

As the number of tests increases, it's now worth grouping related tests into describe blocks

Potential groups:

• Guards
• Simple schema
• Schemas with properties
• Options
  • types
  • autoDescribe
  • hyphenatedDescriptions
  • ....

Hey there, just wanted to let you know that your library doesn't seem to appear on NPM (https://www.npmjs.com/search?q=json-schema-to-jsdoc).

I have installed directly from github for now using the command npm install git+https://github.com/n3ps/json-schema-to-jsdoc.git

I was thinking we could add an option to have the format value be mapped to a specific type.

For example, this:

{
  "type": "object",
  "title": "Info",
  "properties": {
    "someHTML": {
      "type": "string",
      "format": "html"
    }
  }
}

...might produce:

/**
 * @typedef {PlainObject} Info
 * @property {HTML} someHTML
 */

instead of:

/**
 * @typedef {PlainObject} Info
 * @property {string} someHTML
 */

...given:

jsdoc(schema, {
  formats: {
    html: {
      string: "HTML"
    }
  }
});

This would let the schema have more meta-data to guide the type, especially given that formats can hint at a more precise type and one may have definitions one wishes to use for these.

I realized that the string concatenation was becoming too verbose especially with the introduction of indent options.

Planning on refactoring it such that all the JSDoc "lines" are collected first, then formatted together with the indent options at the end.

@brettz9 FYI this might be handy with the maxLength.

Not sure how tricky this would end up being, but it would be nice to have support for a hierarchy of types such that something like:

const schemas = {
  $defs: {
    Person: {
      title: 'Person',
      type: 'object',
      properties: {
        name: { type: 'string', description: "A person's name" },
        age: { type: 'integer', description: "A person's age" }
      },
      required: ['name']
    },
    Laborer: {
      title: 'Laborer',
      allOf: [
        {$ref: '#/$defs/Person'},
        {type: 'object', properties: {skillLevel: {type: 'integer'}}},
      ]
    }
  }
}

...could get mapped to:

/**
 * @typedef {PlainObject} Person
 * @property {string} name A person's name
 * @property {integer} [age] A person's age
 */

/**
 * @typedef {Person} Laborer
 * @property {integer} [skillLevel]
 */

(Note how Laborer inherits from Person in the type portion of the Laborer @typedef.)

(I'm using $defs which is the latest JSON Schema draft's equivalent for what had been definitions.)