Worst Phobos documentation evar!

[Walter Bright via Digitalmars-d]

On 12/29/2014 5:09 PM, Ary Borenszweig wrote:
> On 12/29/14 8:49 PM, Walter Bright 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 :-)
>
> Macros are for code, not for documentation.

?? Text processing using macros has a very long history.


> When wanting to contrirbute documentation you'll have to learn which macros the
> author defined and which ones to use. Again, this makes it harder to write docs,
> not easier.

When I write markdown in github, wiki, reddit, man, troff, md, javadoc, doxygen, 
etc., I have to read the markup doc for that particular flavor and figure it 
out, too.

If there was a standard markup language, you'd be right. But there isn't. 
Everyone invents their own system. I really do not understand this particular 
criticism of Ddoc (several others here have made the same criticism).

(And actually, the Ddoc macro system very closely resembles the one used by 
make, as that is a simple and effective one, well known by programmers.)