Separate RPC documentation from code #12761

I think RPC documentation should be separated from the C++ code itself.

It makes building more tools based on it needlessly complicated, and it also pads the RPC code too much.

I have been thinking how to separate the RPC docs strings from the code itself. My 3 ideas

• make some preprocessor macros and the documentation will be copied to the source code by the C++ pre-processor - that could be a good solution, but maybe hard to decypher?
• keep the docs at separate files (in plaintext/possibly even markup) and let bitcoind read them at runtime - that could create annoying dependencies and probably introduce parsing errors?
• keep the docs at separate files (in plaintext/markup) and "transpile" them somehow to the C++ code at make step

Do you think it's a good idea? And which of the three possible ways is best?

Having the code "padded" with documentation seems like a good thing, not a bad thing to me. It makes the RPC code actually understandable (how else are you supposed to know what request.params[3] means?) and makes it less likely that documentation will become out of date when the code changes.

Also, I could be missing something, but all of the suggestions above seem more complicated than the current help implementation, not simpler. I'd expect it would simplify tooling to structure the documentation, so it wouldn't be necessary to parse the big strings, instead of just moving the strings from one file to another.

Hm. I can see your point.

The idea was just to make automated RPC documentation, such as the one on my experimental website, easier/trivial.

But I also understand that it would make the doc quickly obsolete, as most other online documentations are for example. And since I don't have an idea how to do this in an easy and readable way, I am probably closing this

The idea was just to make automated RPC documentation, such as the one on my experimental website, easier/trivial.

It seems like structuring the documentation more (by breaking up the parameter return information instead of having it all in one big string) could make it easier to generate good documention. There is actually already an issue open for this: #4157, which could be a really nice improvement.