Jeremy and I chatted on IRC about cleaning up NMControl and auto-generating documentation from inline commenting of the API. However, I think that might have been a misstep. NMControl needs to be cleaned up so others can hack on it: better inline commenting, basic documentation, etc.
However, if we are going to spend our time documenting NMControl's JSON-RPC API, we might was well just write a spec using an Interface Definition Language from which we can generate documentation and JSON-RPC client libraries for communicating with NMControl.
While toying with creating a new API for Namecoind last quarter* I gained experience with two solutions for auto-generating JSON-RPC libraries: Barrister-RPC and Haxe.
Barrister-RPC
- Clients in Java, Node, PHP, Python, and Ruby.
- Natively generates Docco-style docs.
- I don't believe it generates unit tests for each target language.
- Probably the most robust solution since it is purpose built for this task.
- Clients in Java, C#, PHP, Python, Ruby, and C++.
- Since the IDL is written in JSON, the documentation would only be semi-automated.
- Should generate native unit tests for all of the target languages.
- NOT purpose built for generating RPC libraries, probably involves more QA.
- Poor tooling for Haxe and the relative immaturity of the language probably negates any of the fancy automated unit testing.
- Would require adding the HTTP transport to NMControls JSON-RPC interface.
I've got a lot of work ahead of me this summer (8-hours of intensive spanish/day, finding a job, moving, etc) so I'm actually leaning towards Barrister-RPC because I think it would be easier to recruit new developers for the task. However, this is a really crucial area of development and I will commit to job once NMControl is to the point that I can test against it.
*I abandoned the Haxe-based API (and the abstractions I wanted) because I figured out a clever way to load everything from the blockchain directly into CouchDB without having to handle each record individually ... thus negating the utility of a generic JS library for Namecoin for the immediate task. That and I decided I should work on other Namecoin stuff and circle back after Haxe's tooling improves.