-
Notifications
You must be signed in to change notification settings - Fork 207
Types documentation
See also agoric-sdk repo's TypeScript doc.
We use JSDoc with Typescript extensions so that the types written in comments are checked statically.
Part of our Coding Style is to use TypeScript to annotate code. The code remains Javascript code, not TypeScript code, with the types defines in JSDoc.
There are some .d.ts files for when the JSDoc supported types don't suffice. (For example, - adding globals).
For optional parameters use brackets:
@param {number} [optionalNumber]
not the Google Closure syntax
@param {number=} optionalNumber NOPE
See also https://github.com/Agoric/agoric-sdk/wiki/Express-optional-parameters-in-both-JS-and-JSDoc-TS-syntax
When type annotations were introduced they were mostly kept out of the code in a types.js file. Over time we've found that it's better to have the annotations with the code.
Many types are still defined in the types.js and available implicitly through imports. Over time we've found that it's better to explicitly import types that are needed. E.g.,
/** @typedef {import('child_process').ChildProcess} ChildProcess */Use unknown rather than any in type declarations (or document justification for any) SES-shim/issues/600
ts-ignore can be ignored forever but ts-expect-error will notify us when the suppression is no longer necessary, so we can clean it up. E.g. https://github.com/Agoric/agoric-sdk/pull/4759/commits/d9b0717d9a0b3691b7fe813c5ba7a99293eb4291
There's a gotcha though with using either, which is that if you suppress on a key in an object the whole object is suppressed. In that case you may want to use any. E.g. https://github.com/Agoric/agoric-sdk/pull/4764
WIP
swingset is a good model.
client code:
/** @type {import('@agoric/swingset-vat').CreateVatResults} */https://github.com/Agoric/agoric-sdk/blob/8da963736b2cf147063787e811b9fe2da0b7e71e/packages/SwingSet/src/index.js https://github.com/Agoric/agoric-sdk/issues/6512
see also: