Update Friday March 22, 2019
Tons of effort over the past week to get these working:
Those are images of the rustdoc documentation I’ve been putting together for the v2 wallet API, and the self-testing documentation for the generated JSON-RPC stubs.
It looks like simple rustdoc documentation, but there’s a lot going on behind the scenes to produce this. That ‘json_rpc_example’ in the image isn’t just documentation, it’s the input to an entire integration test that runs against a sample chain in the wallet’s test framework, with the output carefully compared to the expected results in the documentation. By ensuring documentation and testing are integrated this way, we can pretty much guarantee that both the rust and generated JSON RPC APIs will stay consistent, current and documented going forward. Hugely important, and definitely worth the work.
And what work it is. It goes something like this:
- Sit down to create the json doc/test for a particular function
- Realize function args aren’t that json-friendly, fix them
- Come across obscure bug in serialization preventing example from working, spend hour tracking down and fixing
- Realise fix has to go into grin core, create that PR
- Realise function needs a statically-seeded test RNG to produce consistent output every time, implement that,
- Realise doctest helper functions need more work to support this particular function, implement and test that
- It’s 4 hours later and I’m still working on documenting the same function.
- etc, etc, etc.
It’s been like this for just about every single function, and it’s only just been since I got to the last few functions of the owner API that the testing started to go a bit smoother, as most of the bugs and changes required for testing have been ironed out. The upside is that this has been a great test of the V2 API generation, and this should be invaluable going forward to keep the V2 API clean, consistent and documented. The downside is it’s tedious as hell and I can’t stand looking at it anymore right now. Luckily, it’s mostly there, with most API functions and their doctesting complete. I’ll come back and complete when I’m more fresh, but luckily this big push to get the API documentation started should only have to happen once. Doc and test changes from here on out should be incremental and more focused, and hence easier to bear.
Right, I need to go do something that’s not aligning JSON brackets. Enjoy weekend!