DDoc vs Doxygen (Re: lint for D)

[Bill Baxter]

bearophile wrote:
> Nick Sabalausky or Bill Baxter:
>>> 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.
> 
> This is one of the first examples:
> 
> /*
>    Function: Multiply
> 
>    Multiplies two integers.
> 
>    Parameters:
> 
>       x - The first integer.
>       y - The second integer.
> 
>    Returns:
> 
>       The two integers multiplied together.
> 
>    See Also:
> 
>       <Divide>
> */
> int Multiply (int x, int y)
>    {  return x * y;  };
> 
> It's nice, but it uses too much vertical space, so the eye loses itself in all that space, and the programs become too much long. To improve readability you should  reduce used space.
> 
> The first line: "Function: Multiply" seems redundant (and it's a bad thing) because the true function name and the comments can grow to differ.
> 
> Anyway, I don't know if NaturalDocs creators allow D developers to bundle this NaturalDocs into *every* D distribution present and future.

Actually I don't think Natural Docs really supports D at all.
I was just mentioning it for the overall markup style.

About the vertical space in that example: the space after the labels is 
not required by NaturalDocs.  So it could be a bit more compact.  Still 
it would be nice to be able to say "See Also: <Divide>" all on one line.

About the "Function: Multiply" redundancy, I think that's because the 
whole thing is done as a perl script and it's not quite up to the task 
of parsing C++ to figure out what the next grammatical entity is.

There's also reST (http://docutils.sourceforge.net/rst.html), which has 
been thought out very thoroughly, but the choices they've made for the 
most common markup tasks don't sit well with me.   (Like using :Section: 
for sections, and too many backticks everywhere.)

--bb