Improving ddoc

[Joseph Rushton Wakeling via Digitalmars-d]

On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote:
> Please show some context where that frequently happens for you.
>
> I see some instances in Phobos, but they are all of the form:
>
>    [x .. y$(RPAREN)
>
> which would be better coded as:
>
>    $(INTERVAL x .. y)
>
>    INTERVAL=[$0$(RPAREN)

See, this is my point.  $(INTERVAL x .. y) is, to my mind, less clear to read 
_in the source_ than [x, y).

If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x 
and y.  But is it the closed interval [x, y], one of the half-open intervals (x, 
y] or [x, y) or the open one (x, y) ... ?

I need that kind of precision to document the kind of code I'm writing 
(including phobos contributions), and I would like to be able to read and write 
with that precision explicitly in the source.  If I need to use a macro 
definition, then the reader has to look up that definition, and you just _know_ 
that people are going to use those macros incorrectly, e.g. if we suppose that 
INTERVAL is [x, y), then people will use it in circumstances where they mean [x, 
y] or (x, y) or whatever.

Yes, I could use a right-bracket UTF8 character, but that's finnicky and 
annoying (and potentially runs into other problems for readers, e.g. what if 
someone copy-pastes my ddoc source into a non-UTF8 email?).  And yes, I could 
use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely 
to be confusing to readers.

I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that 
a super-common character in both code and mathematics has problems being used, 
as itself, inside the documentation markup :-)