search

holochain / holochain-client-js

A JavaScript client for the Holochain Conductor API
Other
258 stars 16 forks source link

produce usage documentation #19

Closed Connoropolous closed 1 year ago

Connoropolous commented 3 years ago

to start a discussion, what kind of approach might be reasonable for this?

just write it up in the README? autobuild HTML from typescript types?

Connoropolous commented 3 years ago

dialing in a few stakeholders here to collect thoughts... @guillemcordoba @artbrock @maackle @thedavidmeister @JettTech

Connoropolous commented 3 years ago

I am willing to do some time on documentation, if I have a proposed approach that has buy-in

maackle commented 3 years ago

I'm not sure how instructive generated docs based on types will be on their own, but they'd certainly be helpful.

I guess some actual write-up with examples in the README would be best.

It would be ideal if we already had some documentation on Holochain's conductor API, and then this could be described as a thin layer around that, with some explanation about how to translate between JS and Rust representations of the types. Maybe you could write docs with the assumption that there will also be proper conductor API docs at some point (and an explanation that they don't exist yet).

It also occurs to me that we should probably rename this repo to holochain-conductor-api-js or something, since this is potentially one of many language-specific bindings to the conductor API.

Connoropolous commented 3 years ago

Are you thinking these "proper conductor API docs" would be written right into the core codebase as code comments and part of the cargo generated rust docs?

maackle commented 3 years ago

@Connoropolous probably, yes. Are you suggesting that we could do the same for this repo? Now that I think of it, that makes sense: my comment about generated docs not being helpful was assuming we'd just have the types, but if there were nice doc comments to go with them, that could be good...haven't given it much thought though.

Connoropolous commented 3 years ago

Hey @maackle I've taken a tackle at improving the core documentation of the conductor api docs in https://github.com/holochain/holochain/pull/440/files now...

Can you check it out?

Connoropolous commented 3 years ago

@maackle I've done it in preparation for fixing any breaking changes from https://github.com/holochain/holochain/pull/423 and possibly cleaning up some of the internal code as indicated by #24

zippy commented 3 years ago

There's this now: https://github.com/holochain/holochain-conductor-api/tree/develop/docs

jost-s commented 1 year ago

There's the API docs and there are examples in the README.