[WIP] RPC help tabulation #9686

When writing help output in the RPC commands, people tend to align in the editor. Escaped stuff messes this up on the output end. E.g.

" \"foohash\" : \"hash\" (string, required) The foo hash.\n"
" \"bar\" : n            (numeric, required) The bar.\n"

which results in

 "foohash" : "hash" (string, required) The foo hash.
 "bar" : n            (numeric, required) The bar.

People could try to align for output, but this is hard to get right and requires recompiling every try. I am proposing a simple tabulation function that parses the input string, aligning everything into left of and right of a delimiter (currently " || ").

Is this a reasonable idea? I am not too concerned about performance with this addition, except for the "help" case which runs every single command, but it should be pretty much instant on most machines even with parsing overhead.

Concept ACK. Though to avoid too many intermediate steps it would make sense to make this part of a larger refactor to make the RPC help easier machine-readable. This would make it possible to generate man-pages, wiki pages, etc maybe even simple language bindings from the same source as the "online" RPC help.

@laanwj I like the idea, presuming it's not adding too much overhead to the work of adding/fixing the help content. Not sure what it would look like. A mini-doxygen-parser?

I don't know for sure.

Possibly easiest would be to make the input a (say) JSON file per module, in structured format, then have a script to generate code to include in the build - same principle as for the tests. These JSON files could be used by anything that needs RPC documentation.

(there could even be a way to get unformatted documentation over RPC - say, for RPC clients that want to extract per-parameter documentation from it)

The drawback would be that the documentation is no longer next to the implementation so people may sooner forget to update it. Indeed, something like doxygen could parse the documentation from comments, but that may become too much magic.

The drawback would be that the documentation is no longer next to the implementation so people may sooner forget to update it.

As soon as the documentation is machine readable it is probably easy to compare the output with the documentation and fail if one of the types is not found. The issue, however, is that the output sometimes depends on the input. Or sometimes on command line args such as disablewallet. I am not sure how to handle those cases.

The issue, however, is that the output sometimes depends on the input.

In the help? Can you give any specific examples?

Or sometimes on command line args such as disablewallet.

As an aside, the long-term goal is to get rid of RPCs that behave differently based on availability of the wallet.

In most cases the RPCs are disabled completely without the wallet, which could be handled by importing the documentation for the wallet module only when the wallet is enabled.

More generally these cases can just be documented: Just mention in the text that the behavior depends on someoption. I'd say this is usually clearer to the user than documentation that changes based on some context information.

In the help? Can you give any specific examples?

No, not in the help. Just in the output.

https://github.com/bitcoin/bitcoin/blob/7821db30e16149a3d8b7f467a4e5ac276af6ccbd/src/wallet/rpcwallet.cpp#L1494-L1495

Agree that the documentation should include all cases (thus be static) regardless of input or command line switches.

On Sat, Feb 4, 2017 at 3:49 PM, Wladimir J. van der Laan < notifications@github.com> wrote:

The issue, however, is that the output sometimes depends on the input.

In the help? Can you give any specific examples?

Or sometimes on command line args such as disablewallet.

As an aside, the long-term goal is to get rid of RPCs that behave differently based on availability of the wallet.

In most cases the RPCs are disabled completely without the wallet, which could be handled by importing the documentation for the wallet module only when the wallet is enabled.

More generally these cases can just be documented: Just mention in the text that the behavior depends on someoption. I'd say this is usually clearer to the user than documentation that changes based on some context information.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/bitcoin/bitcoin/pull/9686#issuecomment-277450583, or mute the thread https://github.com/notifications/unsubscribe-auth/AGGmvwMioUjo-NAOvWuxTp9qZiQgKfZ2ks5rZJANgaJpZM4L3BpL .

How about a formatter like we use for --help?

I'm not sure I like moving docs away from sources, but if we do, there are plenty of options. (I'm trying to look at any tools that have a CLI similar to bitcoin-cli (multiple commands, not just options) but can't think of a lot of them, for some reason. Ideas welcome to make this comment more encompassing.)

• Git simply has Documentation/git-[command].txt files, each one being a manpage. See e.g. https://github.com/git/git/blob/35f6318d44379452d8d33e880d8df0267b4a0cd0/Documentation/git-diff.txt
• HomeBrew (macOS package manager) keeps documentation in the source code using special formatting, and then parses that on the fly: https://github.com/Homebrew/brew/blob/master/Library/Homebrew/cmd/help.rb#L76
• RubyGems (gem command) seems to use something similar to HomeBrew but less fancy, e.g.: https://github.com/rubygems/rubygems/blob/master/lib/rubygems/commands/build_command.rb

Will resurrect when/if a solution becomes mature enough for discussion.