Sync Zoe JSDoc with API docs

[dckc]

What is the Problem Being Solved?

Zoe JSDoc that @erights has recently focussed on overlaps with end-user doc by @Chris-Hibbert and co. Let's sync them up somehow

Description of the Design

ref Dec 17 discussion

Also in the ZEstival, @Chris-Hibbert point out docs on Handling Authority

Security Considerations

IOU

Test Plan

the docs repo has tooling for testing examples

https://docs.agoric.com/reference/zoe-api/user-seat.html and related are sourced from JSDoc instead of Markdown

[dckc]

typedoc?

I looked at.typedoc earlier and passed on it because it's for .ts, not JSDoc... But if we head to .d.ts for apis, it could be a match!

[dckc]

@Tartuffo I would think that documentation for our smart contract platform doesn't become critical until after MN-1.

[turadg]

typedoc?

I looked at.typedoc earlier and passed on it because it's for .ts, not JSDoc... But if we head to .d.ts for apis, it could be a match!

Something that understands TypeScript will be necessary. TypeDoc (and presumably other type-smart tools) look for a unified project, so I think we'll need to #4404 to get any type-aware doc generators to work.

[dckc]

just discovered earlier exploration in this area:

• integrate API Doc (reference) with agoric-sdk api-doc documentation#319

[turadg]

#8343 is a fresh attempt.

One package without deps works, but when packages reference each other it chokes because our types don't all resolve as a single project. #4404 would solve that and may make the work worthwhile..

[dckc]

I think we're not quite finished with this one. #8343 says...

Should not be published for external consumption in its current state.

[dckc]

recent work in the area:

• @erights on ownables/revocables feat(zoe): caretaker-style revocable, ownable #8745 (comment)

[dckc]

closely related:

• reference docs for network Port API #8852

[dckc]

There's lots of relevant progress in Agoric/documentation#1038
in particular: https://3c691980.documentation-7tp.pages.dev/reference/agoric-sdk/modules/agoric_zoe.html

yay! I can find a type declaration for ContractMeta using full-text search!

hm... deeply imported stuff is kinda akward

Module: src/contractFacet/types-ambient
https://3c691980.documentation-7tp.pages.dev/reference/agoric-sdk/modules/agoric_zoe.src_contractFacet_types_ambient.html#contractmeta

and there's no prose. (what's the difference between canBeUpgraded and canUpgrade? are they synonyms?)

CopyRecord shows up in this module's list of types.
https://3c691980.documentation-7tp.pages.dev/reference/agoric-sdk/modules/agoric_zoe.src_contractFacet_types_ambient.html#copyrecord

HandleOffer follows the awkward pattern of separating a type declaration from an implementation even though there's only one implementation -- it's not an interface.
https://3c691980.documentation-7tp.pages.dev/reference/agoric-sdk/modules/agoric_zoe.src_contractFacet_types_ambient.html#handleoffer

Invitation has no prose.
https://3c691980.documentation-7tp.pages.dev/reference/agoric-sdk/modules/agoric_zoe.src_contractFacet_types_ambient.html#invitation

prose from README is missing. (artifact of markdown plugin, I think)
https://3c691980.documentation-7tp.pages.dev/reference/agoric-sdk/modules/agoric_zoe.html

and on and on....

cc @LuqiPan @Chris-Hibbert @erights @turadg @0xpatrickdev

[erights]

typedoc does also work on jsdoc in *.js files