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
