JSDoc Annotated Types

[panoply]

Hello,

I was going to create a DefinitelyTyped package for the JS Driver that would contain built-in function JSDoc annotated typings but it would be better adapted to the declarations in v5 as such is somewhat expected without need to pull in a @types module.

I have started here.

I propose the following structure for the comment annotations:

1. Description
2. Linked Reference to Documentation
3. Line Separator
4. JSDocs format @params
5. JSDocs @example

For example:

/**
 * The `Query` function wraps the provided Lambda function, preventing
 * immediate execution, and making the function available for use in
 * index bindings, `CreateFunction`, and ABAC predicates.
 *
 * For example, when creating a named function with `CreateFunction`,
 * `Query` defers execution of the Lambda function until the `Call`
 * function is called.
 *
 * [API Reference](https://docs.fauna.com/fauna/current/api/fql/functions/query?lang=javascript)
 *
 * ---
 *
 * @param {ExprArg|Lambda} lambda
 * The Lambda function to wrap.
 *
 * @example
 * q.Query(q.Lambda('X', q.Var('X')))
 */

Such would render the following for hovers and completions in almost all editors that are leveraging the TypeScript language Server.

---

Though @params is not necessarily required with type declarations, it still feels fitting. The @example renders JavaScript highlighted code blocks and can simply reference the documentation examples, with differences being that the the example expressed in the declarations will use the same argument naming conventions as the types.

Should I PR this when I am done? or have you guys/girls got other plans for such an aspect, ie: scape docs for the context or simply omit annotations all together?

Thanks.

[github-actions]

Internal ticket number is OSS-970

[panoply]

Bumping this cause 4 weeks later no response. If no communication in the next week I will publish it to Definitelytyped which seems rather silly considering I am offering to help on this aspect.