Improving ddoc

[Andrei Alexandrescu via Digitalmars-d]

On 1/1/15 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
> 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 :-)

"Serious flaw" sounds like a serious exaggeration. The notation "[x, y)" 
has unpaired parens. Any tool relying on pairing parens is going to have 
difficulty with it.

This is exactly the kind of argument that diminishes the value of an 
otherwise great notion - that ddoc needs improvements addressing pain 
points with it.


Andrei