Misc #13497: Docs, code samples, Ripper example

• Status: Open
• Assignee: -

[MSP-Greg (Greg L)]

I think it's fair to say that virtually all Ruby documentation today is created by doc generation systems based either on YARD or RDoc. Code samples/examples are common. YARD uses Ripper to parse samples for highlighting, I believe RDoc uses its own parser.

Although I recall previous RDoc parsers to be flexible as to code highlighting, but some seem to be similar to Ripper. Hence, if it can't be pasted into an .rb file and run, it won't highlight.

With many samples, this isn't an issue, but with samples that display multi-line output, there are two options -

1. Comment the whole output section - this will always work, but all lines will render in the commment color.

2. Use an assignment - this will highlight the output (if desired).

Ripper Examples --

RDoc - ruby-doc.org

RDoc - docs.ruby-lang.org

YARD - msp-greg.github.io

Notice how the first two do not highlight the code sample in the overview, or the .lex, .sexp, or .sexp_raw methods.

I edited three source files for the highlighted output, it does require some kind of line similar to 'below is output, shown as assignment to allow highlighting'. The code in the sample doc is exactly as shown. I believe the two RDoc sites will highlight the code if redone in the style shown on msp-greg.github.io. I'd be happy to submit the changes if people find the highlighting helpful.