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 :-)
