The Results section(s) in RPC help text tend to be JSON-like
and are best formatted in code blocks when rendered on the website.
There are some trade-offs for this and related approaches:
- Insert code blocks based on string search of known headings on RPC output Pros:
- Lowest ownership cost
- Good separation of concerns Cons:
- Not robust to changes in RPC headings, however these are not expected to change often.
- Specific to the Results sections
- Insert code blocks in ToDescriptionString() in the node software Pros:
- Best correctness, since boundaries between parts of the help text are well defined at this stage Cons:
- Poor separation of concerns. The node software should not care how RPC help text is rendered beyond the terminal.
- Markdown could be introduced as a format specified via runtime argument to alleviate the above, but this introduces additional maintenance overhead in the node software which is strictly worse than having this overhead elsewhere.
- If Markdown were adopted as the only format, this approach still suffers from degraded usage of vertical screen space.
- Insert code blocks based on string search of JSON-like structures on RPC output Pros:
- Improved rendering of all JSON-like content (not just the Results sections) Cons:
- Difficult to implement correctly. A high number of false positives and negatives would be expected, resulting in low-quality RPC documentation.
- In order to reduce false-positives/negatives, the parsing would need to be aware of most/all Markdown rules.
Given the above, I think option #1 is the most reasonable, so I have implemented it in this patch.