Worst Phobos documentation evar!

[Ary Borenszweig via Digitalmars-d]

On 12/29/14 10:49 PM, ketmar via Digitalmars-d wrote:
> On Mon, 29 Dec 2014 15:49:10 -0800
> Walter Bright via Digitalmars-d <digitalmars-d at puremagic.com> wrote:
>
>> On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
>>> Ddoc isn't too bad, but trying to document examples in dom.d turned into a mess
>>> of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
>>
>> I'd make a macro:
>>
>>      XML=$(LT)$0/$(GT)
>>
>> I use custom macros all the time in Ddoc. If you aren't, you're not doing it
>> right :-)
> that's why ddoc is completely unusable either for reading "as is" or
> for generating separate documentation.
>
> i was very excited about built-in documentation generator in D, and now
> i'm not using it at all. i rarely generating stand-alone docs, they are
> just not handy for me. i prefer to read documentation right in the
> source (yet i still want to have an option to generate stand-alone
> files). did you tried to read Phobos documentation in Phobos sources?
> those macros are pure visual noise. i don't mind if D will understand
> one of the Markdown variants, or textile, or rss -- anything that is
> READABLE without preprocessing, yet can be easily processed to another
> format. i don't mind learning another markdown dialect if i can easily
> read it without preprocessing.
>
> that's why i'm not using doxygen too: it's noisy. seems that most
> document generator authors are sure that only generated documentation
> matters, so source documentation can be of any uglyness. yet if
> documentation is hard to read without preprocessor, it is hard to write
> it too! so people will tend to avoid writing it, and they will
> especially avoid polishing it, 'cause it's write-only, contaminated and
> hard to fix.
>
> D documentation WILL be bad until ddoc will start to understand some
> markdown-like mostly macro-free markup language.

Those are exactly my thoughts.