Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
5 tasks
toliaqat opened this issue Jul 23, 2024 · 8 comments · May be fixed by #9768
Open
5 tasks

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

toliaqat opened this issue Jul 23, 2024 · 8 comments · May be fixed by #9768
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@toliaqat
Copy link
Contributor

toliaqat commented Jul 23, 2024

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...

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

  1. documentation enhancement
  2. documentation enhancement
  3. documentation
    0xpatrickdev
  4. bug
@toliaqat toliaqat added the enhancement New feature or request label Jul 23, 2024
@dckc dckc self-assigned this Jul 23, 2024
@dckc dckc linked a pull request Jul 24, 2024 that will close this issue
@dckc
Copy link
Member

dckc commented Jul 24, 2024

re inline KnownChains making Orchestrator messy:

@dckc
Copy link
Member

dckc commented Aug 1, 2024

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

image

@dckc
Copy link
Member

dckc commented Aug 14, 2024

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

@dckc
Copy link
Member

dckc commented Aug 14, 2024

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
Copy link
Member

dckc commented Aug 29, 2024

Documentation of failure modes would be nice.

@dckc
Copy link
Member

dckc commented Aug 29, 2024

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

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

mergify bot added a commit that referenced this issue Sep 9, 2024
refs: #9757

## Description

A bunch of docs improvements to get into the u17 release.

This doesn't do all the things specified in the ticket so leaves open:
- #9757 

### Security Considerations
n/a

### Scaling Considerations
n/a

### Documentation Considerations
We'll need tutorial docs. I think some of the `@example` suggestions make more sense there.

### Testing Considerations
CI

### Upgrade Considerations
not yet deployed
@dckc
Copy link
Member

dckc commented Oct 3, 2024

@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
Copy link
Member

0xpatrickdev commented Oct 4, 2024

@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

mergify bot added a commit that referenced this issue Oct 4, 2024
refs: #9757

## Description
- export types for `PortfolioHolder` and `CombinedInvitationMakers` for use in typedoc
- improve typedoc copy 

### Security Considerations
n/a

### Scaling Considerations
n/a

### Documentation Considerations
This PR makes these exos appear in typedoc docs:
- https://e46fc33c.agoric-sdk.pages.dev/funcs/_agoric_orchestration.preparePortfolioHolder
- https://e46fc33c.agoric-sdk.pages.dev/funcs/_agoric_orchestration.preparePortfolioHolder

### Testing Considerations
n/a

### Upgrade Considerations
n/a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants