search

Agoric / agoric-sdk

monorepo for the Agoric Javascript smart contract platform
Apache License 2.0
304 stars 191 forks source link

Sync Zoe JSDoc with API docs #4291

Open dckc opened 2 years ago

dckc commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

turadg commented 1 year ago

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 https://github.com/Agoric/agoric-sdk/pull/4404 to get any type-aware doc generators to work.

dckc commented 1 year ago

just discovered earlier exploration in this area:

turadg commented 10 months ago

https://github.com/Agoric/agoric-sdk/pull/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. https://github.com/Agoric/agoric-sdk/pull/4404 would solve that and may make the work worthwhile..

dckc commented 7 months ago

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

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

dckc commented 5 months ago

recent work in the area:

dckc commented 5 months ago

closely related:

dckc commented 3 months ago

There's lots of relevant progress in https://github.com/Agoric/documentation/pull/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 commented 2 months ago

typedoc does also work on jsdoc in *.js files