DDoc vs Doxygen (Re: lint for D)

[Nick Sabalausky]

"Bill Baxter" <dnewsgroup at billbaxter.com> wrote in message 
news:g56avu$56h$1 at digitalmars.com...
> 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.

True. I have noticed that.

>
> 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.
>

Very nice. I think I've come across that once before, actually, and then 
promptly forgot about it. But the idea that automatic documentation syntax 
could be made so natural-looking while still performing the job, all with 
such simple parsing rules... Well, that really stuck with me and I was never 
able to look at C#'s documenting comments the same way again.

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