Pete Gonzalez

FYI this came up recently in a discussion https://github.com/microsoft/rushstack/issues/1874#issuecomment-633883380 for the API Extractor project, where someone was using the [purify](https://gigobyte.github.io/purify/) library to model JSON objects. (Probably it's related to your...

Let us suppose that you wrote TSDoc comments like this: ```ts declare const isConfig: y.ObjectSchema

@jayarjo Are you proposing something like this? ```ts /** * @property image - the URL of the image * @property name - the name of the thing * @property env...

For APIs intended for third parties, generally we recommend to give a name to the interface, for example: ```typescript /** Options for {@link ItemCollection.add} */ interface IAddItemOptions { /** the...

@seanpoulter I moved your question into a separate issue, since it's a separate topic.

@dschnare do people commonly do this in a real world public API? This practice seems to be entangling the internal implementation details of `callHome()` with its public API signature. It...

Fair point. But how would you propose for TSDoc to handle that?

Seems reasonable. :+1:

This seems fine to me, particularly since JSDoc has the same solution: ```ts /** * @param args * @param args.a - Placeholder * @param args.b - Accepted values * @param...

👍 Yes, we should definitely implement this! Doing so would enable a tool like API Extractor to normalize the comment format when it writes a .d.ts file for release. Another...