Inline code in the docs - the correct way

[Jonathan M Davis]

On Wednesday, January 31, 2018 16:19:53 H. S. Teoh via Digitalmars-d wrote:
> In general, almost all text macro / formatting systems, from LaTeX to
> HTML to ddoc, are universally ugly and verbose when it comes to tables,
> and makes my eyes bleed. The only exception I've found so far is
>
> markdown, where you can actually write this:
>   |Blah|Blah|
>   |----|----|
>   |abc |def |
>   |ghi |jkl |
>
> It's not perfect, but it's worlds better than the line noise syntax of
> the alternatives.

Yeah. Tables are generally ugly, though they're also not super-common in
documentation - perhaps enough to be annoying, but most functions don't have
them.

> Actually, for me it's not so much a matter of "it's faster to type";
> it's more of an issue of "when I'm reading (and presumably thinking
> (hard) about) source code, do I really want to expend the mental
> resources to parse the syntax of yet another embedded DSL inside a
> *comment*?".  If I had my way, I would just write a normal comment as
> opposed to a doc comment.  What makes the doc proposition attractive is
> that, in an ideal world, a "normal" comment can be automatically
> translated into nice docs without needing to pepper-spray it with
> foreign syntax particles, so that I can read the comment while working
> on the code, in addition to having nice docs to show to others in a
> format they prefer, like HTML or whatever.
>
> That's why I would actually welcome markdown-like syntax in ddoc. Yeah,
> it has limitations and sux in many ways, but IMNSHO you shouldn't be
> reimplementing complex HTML syntax inside a doc comment anyway -- leave
> that to an external templating engine or whatever you wish to use, and
> just let the doc comment be as readable as possible *as source code*.

Personally, I hate markdown, because it makes certain syntax magical - e.g.
it's not uncommon that a commit message ends up looking bad when github uses
it as the message for a PR, because some piece of code contained * or some
other piece of syntax that markdown decides to do something magical with.

I _much_ prefer the explicit syntax used by ddoc, so I can't say that I'm at
all happy at the idea of markdown syntax being added to ddoc. Ddoc is by no
means perfect, but I don't see adding magical syntax as being a particular
nice fix. Clearly, there's some disagreement on that front however.

Personally, I actually like the fact that the website is done in ddoc, and
while sometimes it looks ugly in the documentation, it mostly looks just
fine. IMHO, the main problem with ddoc for documentation is that it doesn't
automatically handle stuff like cross-links, and it fundamentally can't,
because to do that properly, you have to generate all of the docs at once
with a standard layout for where everything goes so that the links can link
to stuff. To get it right, the compiler would have to actually act like a
documentation generator and not just like it's compiling a file to ddoc.

- Jonathan M Davis