Support `format`

[brettz9]

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.

[n3ps]

Interesting proposal. I assume you're referring to https://json-schema.org/understanding-json-schema/reference/string.html#format

Did you choose an object to define format in anticipation of more meta data? I see that this if present, it replaces @property type, what are other use cases?

[brettz9]

Right, that property.

The idea with the object on the formats option is so that one could define different format and type combinations. The reason the format subobject accepts different types for keys is that it is theoretically possible one could have the same format name on two different types. For example, perhaps there could be a directive to format a number as an integer, even though it could be floating point. The type might differ for integer and number. It is not a burning use case I have but merely to recognize that format varies independently of type, but it makes sense to be able to take type into account in case the same format is reused for different types.

For example:

jsdoc(schema, {
  formats: {
    html: {
      string: "HTML",
    },
    int: {
      integer: "Integer",
      number: "Number"
    }
  }
});

[n3ps]

I see, so it's like a lookup table of type-format combinations.

[brettz9]

Right. #44 adds to the just merged PR in applying the new formats lookup table results to @property as well as @typedef while at the same time applying the plain types lookup table to @property as well (as it had not been previously either).

[n3ps]

Alright. Are you planning on adding it to the Readme?

Also noticed the test.js just is over the 1000-line mark. Once this format feature is in I'm thinking of doing s\some refactoring/reorganizing.

[brettz9]

Thanks for the merge... And my apologies, forgot that---have submitted #48 to add to the README (and added a test corresponding to that README example to continue ensuring all the examples are functioning as intended).