Property & Type Descriptions, Comments and Documentation?

[pdfowler]

We're updating our feathers api code to use TypeBox as the source of truth for our models and types, but struggling with the DX while viewing (within VSCode) the associated metadata (eg: description) for each field. I'm guessing this is more of a VSCode issue, but wanted to raise the question here first.

Code	VSCode Tooltip	Useful?
/** the uuid of the user who created the note */ author: IUser['uuid'];		👍
/** * @title * author * @description * the uuid of the user who created the note * */ author: IUser['uuid'];		👍
author: Type.Optional( Type.String({ description: `@title author @description the uuid of the user who created the note`, }), ),		👎
/** * @title * author * @description * the uuid of the user who created the note * */ author: Type.Optional( Type.String(), ),		👍

So, is adding the block comment to my TypeBox schema the only way to get field information to appear in VSCode? My ideal state would be that the description would be stored in the schema's description field (structured) and not as a comment for each field. If so, I'm afraid we start getting into a worst-case-scenario of this info being duplicated in the block comment and in the schema's description field.

TL;DR:

1. Is there any way to update the Static<T> type to make the description field (and title) more available to VSCode?
2. Is this an issue I need to raise with the VSCode team; making a push for improved support for TypeBox/json-schema as opposed to just the field's comments.

[sinclairzx81]

@pdfowler Hi,

Unfortunately (and to the best of my knowledge) there isn't a way to map JSDoc comments onto types through the TS type system. At this time it is only possible to retain existing user defined JSDoc comments (as per example 4) where the compiler associates the comment with the property, and where mapping that property carefully will also bring the comment over.

This limitation is mostly due to current capabilities of TypeScript's type mapping syntax, where there isn't a way to programmatically map comments. However, something like the following would be ideal...

// Where the doc comment string can be interpolated via ${...} inline using template literals types.
type T = number extends string ? {
  /**
   * @description ${'I'm a number'}
   */
  x: number
} : {
  /**
   * @description ${'I'm a string'}
   */
  x: string
}

...where the ${...} could be substituted for literal strings present on the type being mapped (for example the description field on SchemaOptions). But it's uncertain if this functionality would be feasible in TS as I expect TS would have to do some double evaluation of the doc comment to yield a type (noting doc comments can also be used for type inference annotations), but interesting to think about.

Because of the above limitation, users will need to duplicate both doc comment and description field to get both intellisense hints and schema metadata (which is unfortunate). However, I am mindful of new compiler / language features rolling through, so should TS provide some facilities for this use case, I would certainly spend some time trying to integrate (as it fits inline with TB's goals to be both TS and JSON Schema aligned, which extends to doc comments as a component of the TS language) - See here for some initial prototyping work in this area.

Hope this helps!
S

[pdfowler]

Thanks for the detailed response. Based on my limited digging, I had figured that was the case but I'm glad I asked. I'd love to have eyes on any new language features being discussed - have you seen any specific issues on the microsoft/typescript org related to this.

Also, it looks like your link is either borked or the repo is private. Would love to take a look

[sinclairzx81]

@pdfowler Whoops, try here for the link (this project got renamed recently)

have you seen any specific issues on the microsoft/typescript org related to this.

Unfortunately no. The jsdoc code example was just imaginary code that would be necessary for comment mapping (or something like it), But I wouldn't expect this to be a language feature any time soon (but would be super nice to have)

Could be worth putting a suggesting out on the TS repo, the TS community may have some interesting thoughts on it. But as a feature, it might be a bit of a long shot (at least in the short term)

Cheers
S