DDoc vs Doxygen (Re: lint for D)

[Bill Baxter]

Nick Sabalausky wrote:
> "Walter Bright" <newshound1 at digitalmars.com> wrote in message 
> news:g55rle$1uoh$1 at digitalmars.com...
>> Bruce Adams wrote:
>>>  From what I hear about ddoc it is vastly inferior to Doxygen (speaking 
>>> as usual from ignorance).
>> Ddoc's purpose is to:
>>
>> 1. set a minimum standard for documentation
>> 2. allow documentation to be written in a typical comment style
>>
>> At that, it has succeeded spectacularly. Prior to Ddoc, for example, the 
>> Phobos documentation stunk.
>>
>> My issue with Doxygen is that:
>>
>> 1. it won't get used consistently (being a third party tool) and so no 
>> minimum standard
>> 2. the documentation comments look like another programming language
> 
> I'm not very familiar with Doxygen, but from the sound of it, it reminds me 
> of the XML-based documentation C# uses. Ie, seems alright by itself, but 
> it's garbage compared to Ddoc. With Ddoc, I can actually read my own 
> comments! Maybe Doxygen and the C#'s thing have extra features, I don't 
> know, but to me I can't imagine it being worth giving up the ability to use 
> a very natural and unobtrusive style when writing my documentation-comments.

Doxygen only looks like another programming language if you try to use 
every single feature it provides.  If you stick with the basic the set 
of features (basically, the things that DDoc provides) it looks pretty 
much like DDoc.  My main gripe with DDoc is that those 
$MAKE_THIS_BOLD(macros) everywhere look ugly.  Much uglier than 
Doxygen's keywords like @param, IMHO.

NaturalDocs is nice (http://www.naturaldocs.org/).  It really does a 
much better job of delivering on point 2. above than DDoc does (i.e. 
using typical comment style).  Unfortunately it hasn't really caught on. 
  Here are the examples: http://www.naturaldocs.org/documenting.html.

But I think CandyDoc for DDoc gives the nicest output of all the options 
I've seen.

--bb