It would be very neat if the text between toplevel square brackets in documentation strings could be rendered in the same way that code is rendered in Down.help (). For instance, the doc for List.map would render as:
map f [a1; ...; an] applies function f to a1, ..., an,
and builds the list [f a1; ...; f an]
with the results returned by f. Not tail-recursive.
That can be achieved pretty easily by splitting the docstring around toplevel [ ]. I choose the List.map example on purpose since then, one not accustomed with ocamldoc syntax may be confused by raw [ ], mistaking them for 'a list delimiters.
I would go even one step further and suggest such brackets should be erased when rendering on a dumb tty. This assumes documentation comments follow that syntax but this is pretty much a standard.
It would be very neat if the text between toplevel square brackets in documentation strings could be rendered in the same way that code is rendered in Down.help (). For instance, the doc for
List.mapwould render as:That can be achieved pretty easily by splitting the docstring around toplevel [ ]. I choose the
List.mapexample on purpose since then, one not accustomed with ocamldoc syntax may be confused by raw [ ], mistaking them for'a listdelimiters.I would go even one step further and suggest such brackets should be erased when rendering on a dumb tty. This assumes documentation comments follow that syntax but this is pretty much a standard.