Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

On Mon, Dec 29, 2014 at 11:12:54PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
> >$(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns `true`  )
> 
> Would that still work if the first column was something like (0,0) -
> including a comma?
> 
> I've advocated nicer macros before, ddoc's recursive expansion makes
> for a lot of nice options, but the comma being a separator kinda
> worries me.

We've already had to resort to $(COMMA) hacks to work around comma
issues in Phobos docs. :-(


Not to mention that as it stands, ddoc is only really convenient for
HTML output; while it's certainly *possible* to target it for non-HTML
output, it's a pain. Take LaTeX, for example. You have things like
"Mr.\ So-and-so" (i.e., backslash followed by a single space) for
inserting space of the appropriate width after a period (.) that doesn't
end a sentence, where a normal "." would introduce end-of-sentence
spacing. The only way to fully support this in ddoc is to use $(DOT) or
some such hack instead of writing a literal ".". Or take the various
dashes: "--" for ndash, "---" for mdash in LaTeX, but "–" or
"—" for HTML, respectively. Again, the only way to correctly
support this in ddoc is to define $(MDASH) and $(NDASH) macros. So
instead of writing dashes in your ddocs, you now have to write the much
more verbose and far uglier $(MDASH) and $(NDASH). But it gets worse.
Certain character sequences in LaTeX need to be escaped; for example "$"
needs to be written as "\$", whereas it can appear literally in HTML.
Again, the only solution is $(DOLLAR). Ditto for opening/closing
quotation marks, which are `` and '' in LaTeX, and “ and ”
in HTML. And non-breaking space, which is ~ in LaTeX, and   in
HTML. So now, what was originally an easily-readable documentation
comment:

	Returns: A range of dollar amounts -- if the input is $100 or
	more, as stated in Dr. Watson's "A One" specs; otherwise an
	empty range.

becomes this monstrosity:

	Returns: A range of dollar amounts$(MDASH)if the input is
	$(DOLLAR)100 or more$(COMMA) as stated in Dr$(DOTSPACE)Watson's
	$(RDQUO)A$(NBSP)One$(LDQUO) specs; otherwise an empty range.

Or, for that matter, the fact that LaTeX is sensitive to spaces in
certain contexts, so Walter's formatting trick for Ddoc tables will fall
flat on its face by introducing extraneous space where there shouldn't
be spaces in the output.

Or math symbols, which in LaTeX can be placed in-line by delimiting with
$...$ pairs, with no HTML equivalent. Meaning that you'd need a
$(MATH...) macro with every literal inside encoded as a separate macro,
because LaTeX math mode interprets characters differently and a
different set of escape characters are necessary, but since ddoc doesn't
have contextual escaping of characters, the only way to do this properly
is to write things like:

	Returns: $(MATH $(SQRT $(LPAREN)$(POW $(LIT_x), $(LIT_2))$(PLUS)$(LIT_1)$(RPAREN))).

instead of:

	Returns: $\sqrt{(x^2 + 1)}$.


In my own code, I avoid the macro capabilities of ddoc like the plague,
and stick to just plain text. The only macro usage is for stylesheet
configuration (i.e., setting up HTML containers with the right styles
for the text). It's really hard to read code comments otherwise; the
macro syntax *is* ugly (even if it's better than other markup
languages). Where horizontal formatting is needed, I just use code
blocks (that at least get fixed-width formatting so it's easy to manage
without degrading into macro/tag soup).  Macros are useful for overall
styling and placement of elements on the page, but they are tedious and
ugly for text-level elements, and underpowered.


T

-- 
For every argument for something, there is always an equal and opposite
argument against it. Debates don't give answers, only wounded or
inflated egos.