Incomplete jsdocs for Orchestration API types, variables, methods and parameters

[toliaqat]

What is the Problem Being Solved?

The current @agoric/orchestration reference docs (JSDocs) are incomplete for the purpose of devrel to write stuff in docs.agoric.com.

Several methods and parameters are missing detailed descriptions, which hinders the ability of developers to understand and utilize the API effectively.

The missing Orch API JSDocs can be tracked on...

• Orch API JSDoc Tracking

Expected Behavior:

The JSDocs should provide comprehensive information for all methods, including:

• A clear and concise description of each type, method, and variable.
• Detailed information on each parameter (name, type, description).
• Return type and description.
• Examples demonstrating how to use the API.

Tasks

Beta Give feedback

1. ReturnType<...> idiom obscures reference docs for public APIs #9765
   documentation enhancement +2
2. types with methods should be documented as typescript interfaces #9766
   documentation enhancement +2
3. Orch docs have too much inline chaininfo #9992
   documentation +1
   
4. Use of internal TypedPattern in external APIs is awkward / obscure #9994
   bug +1
5. exos/README.md needs to be refreshed and reviewed before NPM release

[dckc]

re inline KnownChains making Orchestrator messy:

• Can I hide a specific function's "type parameters"? TypeStrong/typedoc#2273

[dckc]

Why is connectionInfo: IBCConnectionInfo referring to the type by name as expected but type for chainInfo is expanded???

[dckc]

OrchestrationFlow has no prose, but there's an Orchestration Flows blurb on the @agoric/orchestration page. That blurb should probably move.

[dckc]

GuestOf could really use an example; in Office Hours, we started drafting one:

modified packages/async-flow/src/types.d.ts

@@ -39,6 +39,12 @@ export type HostAsyncFuncWrapper = (
  * The function from the host as it will be available in the guest.
  *
  * Specifically, Vow return values are converted to Promises.
+ *
+ * @example
+ * const localTransfer = (...) => { return asVow(() => ...); };
+ * @param {GuestOf<ZoeTools['localTransfer']>} ctx.localTransfer
+ *
+ * from `orchestration/src/examples/sendAnywhere.flows.js`
  */
 export type GuestOf<F extends HostAsyncFuncWrapper> = F extend

[dckc]

Documentation of failure modes would be nice.

[dckc]

Functions / methods whose results await actions from other chains should be flagged.

In general, anything with cost > O(1) amortized should be documented.

[dckc]

@0xpatrickdev in Documentation Considerations of #10211, you write...

These tests serve as documentation for using the Deposit, Withdraw, Transfer, and Proxying invitationMakers from the Orchestration API

Do we have any JSDoc for those? I'm struggling to find PortfolioHolderKit at all in @agoric/orchestration API docs.

[0xpatrickdev]

@0xpatrickdev in Documentation Considerations of #10211, you write...

These tests serve as documentation for using the Deposit, Withdraw, Transfer, and Proxying invitationMakers from the Orchestration API

Do we have any JSDoc for those? I'm struggling to find PortfolioHolderKit at all in @agoric/orchestration API docs.

Good question, PR'ed here: #10217