Worst Phobos documentation evar!

[Walter Bright via Digitalmars-d]

On 12/29/2014 4:37 PM, Kiith-Sa wrote:
>> If you're not using custom macros, and you find Ddoc tedious and repetitive,
>> you're using it wrong.
>
> I cannot use a custom macro to shorten $(D a == b). A well-written paragraph
> will have 20 such $(D XXX), $(B XXX), $(I XXX), not to mention $(SOMELINK
> xxx.com XXX).

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


> And there's no way to make lists or tables readable:

Yes, there is. I just showed you.


> Yes, *you* use DDoc all the time. But *you* are also forcing it on everyone
> using the language, and on any average programmer who may potentially use D,
> most of whom don't share your love for macros and MANY of whom know much more
> common formats like Markdown. Most people don't write their docs in LaTeX either.

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'm writing my *thesis* in ReStructuredText, which is basically Markdown on
> steroids with *way* more special characters than Markdown, and I almost never
> need to escape anything.

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


> to be usable, documentation must be as simple to generate as:
>
>    doxygen Doxyfile

     dmd -D source.d

(And you don't have to go find a doxygen that works on your system, is 
compatible with D source code, and is installed correctly.)

BTW, you can use Doxygen with D if you want to.

In fact, some people used Doxygen with D before D had Ddoc. If that actually 
worked out well, Ddoc would never have been created. But it did not work out 
well. It was a disaster. Few wanted to be bothered with installing Doxygen, so 
what happened was little to no documentation got written. The Phobos docs often 
bore no resemblance whatsoever to what the code did.

Ddoc revolutionized all that. It's hard to understate how desirable it is to 
have it built in to the compiler, meaning everyone has it, and has the correct 
version of it.

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