Write good documentation.
Opened this issue · 4 comments
We, need to have separate doc page or wiki page.
I think a format that works well for Rust is writing a tutorial module, so the docs are tested by the toolchain, sit along the "reference" doc, can be viewed both locally and on docs.rs, and aren't tied to github.
That said, I'm not sure there's a big need for separate doc pages ? There's certainly scope for improving the module-level docs, the inline docs and examples (I've got some WIP for utils.rs), but mqttrs has a very straightforward API to begin with.
I've started writing an MVP sync client (no CLI option, just connects, subscribes, publishes one message, and exits) using std and bytes only, but it's currently buggy. I think we should provide that and an async example using tokio (should we use the latest version with async/await ?) or libstd-async. I'll also link to my server as soon as it's FOSS, as a full-size tokio example (currently using tokio and old-style futures, but might eventually switch to async/await).
I'll try to finish that MVP client example, and get the server released.
Yes that is what i was thinking. one of the issues i have faced using libs is, i didn't know how to integrate this with other popular frameworks. so, if we can provide something like that, it makes very easy for lib users to just read the example and get on with the job instead of reading the whole docs or code.
Not really documentation per se, but I've finally opensourced https://github.com/vincentdephily/mqttest, which could be mentioned as a code example. I won't make a PR just for a readme, but I might manage to finish the MVP client example in the next few weeks, and send a PR with both.
@vincentdephily nice work.