bitcoin/bitcoin.org — pull request #693 by harding (2014-12-25 00:07:37+00:00)
Title: Dev Docs: Add 114 Pages Of New/Rewritten RPC Docs

Preview: http://dg1.dtrt.org/en/developer-reference#rpc-quick-reference

**Note:** I plan on merging this January 1st even if it doesn't get any full reviews. Please comment if you oppose that plan. This is a large amount of text and very boring to read, so if nobody has reviewed it within a week, I expect nobody will ever review it. We still display a disclaimer telling users about the high probability of mistakes.

### Major Improvements

* Better formatting---the tabular format names elements, types them, and describes them all in the same location, making the docs easier to read.

* More information---the previous RPC docs were based on the help text. These docs were rewritten as I read the source code. This provided me much more information and allowed me to write better descriptions.

* Easier maintainability---the tabular format is much easier to update as Description fields can say "updated in Bitcoin Core n.nn.n" and the Quick Reference section emphesizes recent changes. This makes possible one of my goals: updating the RPC docs throughout the release cycle as changes get merged into Bitcoin Core master.

* v0.10.0 Ready---the reason I started this work: we now document all the new RPCs and RPC updates from the v0.10 Bitcoin Core branch (except for the hidden RPCs). All examples have been re-run with Bitcoin Core 0.10.0rc1 (2014-12-23), and the example updated if anything changed. I'll keep diffing to make sure nothing changes between that tag and the final release.

### Minor (But Fun) Improvements

* More colorful---all RPC examples now use Pygments syntax highlighting.

* Less redundant---reading the source code let me see where several RPCs all used the same functions, allowing me write descriptions once in a variable and then use that variable in every RPC description that used the function. I didn't go crazy and variablize everything---just long segments of documentation.

* Less byte order confusion---we now mention hash byte order wherever it matters (with links to our docs about it), hopefully decreasing confusing among new developers.

* See also---each RPC ends with a See Also section pointing to other RPCs and reference information to help readers navigate RPCs by relationship.

### Not Improved

* GetBlockTemplate undocumented---instead of trying to document GBT, we point to its Wiki page, BIP22, and BIP23. I will document GBT someday, but it's the largest RPC by a sizable margin and mining stuff is currently low priority for me.

### Future Work For Subequent Pulls

* Describe errors---the human-readable RPC error messages tend to be satisfactorily descriptive, so further documentation of them is low priority to me.

* Link to various libraries---I plan to check out a few libraries for JSON in general and Bitcoin Core in particular and write some examples for the examples page.

* Backlink to Bitcoin Core---once 0.10.0 final is released, add links from each RPC's See Also section to its declaration in the source code, or maybe to Wladimir's Doxygen page.

* Maybe document the new hidden RPCs? Opinions on this welcome: I lean towards not documenting stuff the developers aren't displaying to regular RPC users.

A more straightforward description of the changes can be found in the commit message.