Worst Phobos documentation evar!

[Kiith-Sa via Digitalmars-d]

> As opposed to some other markup language. You're always going 
> to have 20 such markup instances, one way or another.

There's a big difference between the amount of visual noise 
between different instances. I'm using D for 5 years and when I 
still find DDoc laced with $(LI $(B bold) $(D code)) hard to read.

>> And there's no way to make lists or tables readable:
>
> Yes, there is. I just showed you.

I don't consider that to be readable, especially, as I mentioned, 
if the items are long lines of non-plain text.

> No matter what form Ddoc takes, it will force some method upon 
> users. However, you can use Doxygen on .d sources if you prefer.

I don't use it because it doesn't *really* understand D.
I'm not arguing for Doxygen's syntax / D support or lack thereof.
I'm arguing for its user experience.

> The D language has a use for most every character, so escapes 
> will be needed a lot.

D blocks in DDoc are usually in:

---
code here
---

With a Markdown-like syntax, inline code could  be in `inline 
code here` .
I admit you would need to escape the backticks, which are very 
rare,
especially in inline code fragments. I also admit *that* would 
force you
to not reliably use *some* D code fragments *outside* backticks. 
And I
find it unlikely that there are more than 3 fragments in entire 
Phobos doc
this would break.


>> to be usable, documentation must be as simple to generate as:
>>
>>   doxygen Doxyfile
>
>     dmd -D source.d

The result takes a shitload of work to make it useful, especially 
if
your project has more than 1 module (and no, passing more files 
won't help
with that).
THIS is useful (it's very close to what Doxygen spits out by 
default):

http://irrlicht.sourceforge.net/docu/index.html

D claims to have a builtin documentation generator, but you can 
either spend a week searching for nonexistent documentation about 
how to make decent documentation *or* you can get a third-party 
documentation generator, which is the same experience you get 
with C++ and Doxygen.


> The only place anyone has to use Ddoc is in the Phobos 
> documentation. If Doxygen is better, more convenient, etc., why 
> aren't you using it? Ddoc must be doing something right :-)


I'm modifying a third-party documentation generator to support 
Markdown and to get decent "Doxygen doxyfile" user experience 
right now.