Document MUXRPC in go-sbot
Closed this issue · 11 comments
So I guess we need to decide on the 'what' and the 'how'.
What
- Endpoint
- Arguments (type and contents)
- Options
How
Not sure...ideas? Markdown document? Code comments? Both?
I had to figure out a lot of the 'what' while working on kuska (see: https://github.com/Kuska-ssb/ssb/blob/master/src/api/helper.rs). Some endpoints expect arguments as an array, while others must be an object (struct in Rust) or a tuple.
Not sure...ideas? Markdown document? Code comments? Both?
I feel like we could use https://go.dev/blog/godoc to document the endpoints in https://github.com/ssbc/go-ssb/tree/master/plugins but finding them in a generated go doc under "plugins" probably isn't the most discoverable thing. Perhaps it needs a separate Markdown document alright. I guess that since kuska exists, and hopefully more clients, that these docs will "keep up" by being an actually living reference for clients and therefore if they don't tell the truth, we'll catch it together.
I had to figure out a lot of the 'what' while working on kuska
@mycognosist Maybe just sketching out a quick docs example of an endpoint that you know well and trying to imagine what you would have liked to have, would be enough? Since you've presumably been struggling with this lack of docs, you're mostly likely in the best position to lay out what is needed.
I think the RPC docs by @boreq provide a great example of what this could look like. The information in the requests section of those docs is very helpful when building out a client (e.g. https://dev.planetary.social/rpc/invite_use.html#requests).
We could potentially start with just documenting the request side of each endpoint and later add the response equivalent.
Ah yes, those docs are really great. I guess we're running into the wider #ssb-documentation issue where there is no shared / centralised documentation repository where we can work together on stuff. Would it make sense to have a call one day @mycognosist @boreq @soapdog (and who else?) to see if we can unify our efforts? I'd love to see the go-ssb MUXRPC documentation efforts link up with existing ssb docs energy.
DM'd on ssb to try to strategise further.
Not everything is documented but it's a solid start!
Some stuff is missing from the client, some stuff from actual MUXRPC handlers. Hopefully more clients pick up MUXRPC calling code and then the requests will start coming in for unifying these interfaces. For now, we have docs parity (more or less) with what Kuska does and that is a solid client.
Terrific work. Thanks so much! This is a huge leap forward 🖤
Closing this off for now with #247 👍