[Dlang-internal] Potential changes to DDoc

[John Gabriele]

On Wednesday, 24 January 2018 at 23:55:12 UTC, David Gileadi 
wrote:
>
> We can pick out parts of Markdown to support, but it won't be 
> true to the intended vision of Markdown and it will have the 
> effect of annoying people who know Markdown because when they 
> try to write it the way they're used to it won't do what they 
> expect ("wait, I can only use + for lists? I always use dashes! 
> And why aren't my headers working?") [2].
>
> If we go this route then we shouldn't say we support Markdown.

What do you think about supporting two modes of operation:

   * one with ddoc markup plus a conservative limited
     subset of CommonMark to enhance ddoc, and

   * one which just assumes doc comments are exclusively
     CommonMark Markdown

?

Not sure if this discussion is strictly limited to documenting D 
and phobos.

New users coming to D and creating modules for code.dlang.org 
will (do?) balk at having to learn yet another custom 
markup/macro format for their doc comments. It's hard enough to 
get people to write any docs at all, let alone ones in a 
language-specific format (see Racket's Scribble, Perl's POD, 
Python's ReST, Ruby's RDoc), *let alone* good docs. Would be 
great if they/we could just use common Markdown.

Another thing to note, since D is often compared to Rust: Rust 
doc comments are in markdown, and that has worked out very well 
for them.