DDoc vs Doxygen (Re: lint for D)

[Leandro Lucarella]

Bill Baxter, el 11 de julio a las 09:54 me escribiste:
> >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.

I really like RestructuredText[1], in combination with Sphinx[2] it make a
great tool to write documentation (reference and tutorial like).

Too bad is too Python-specific...

[1] http://docutils.sourceforge.net/rst.html
[2] http://sphinx.pocoo.org/

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
More than 50% of the people in the world have never made
Or received a telephone call