Descent generated documentation

[Ary Borenszweig]

Lutger escribió:
> This is simply the most useful documentation tool for D even if you would 
> not improve it's appearance!
> 
> It's fast, concise and quick to navigate, I like it a lot.
> 
> Some random remarks:
> 
> I'd like to see the hierarchy, implemented interfaces and such before class 
> ddoc comments. (because some comments can be long)

Good suggestion.

(this is like that in Javadoc, I didn't notice)

> 
> I assume you plan to do something with visibility?

Yes. I just coded this very quickly without paying much attention to 
details. I wanted to see if I could implement the "important" things 
first: links, hierarchy, subtypes, etc.

I think I also missed to list the functions. :-P

(I collect them, I just forgot to list them)

For visibility, you'll be able to choose the maximum visibility level 
you want to document. This is useful to generate documentation useful 
for the writers of the API, to see the organization of the code.

I'll also document public symbols even if they don't have ddoc comments. 
I think that "feature" of ddoc is really annoying, because you'll have 
to document with empty comment public aliases and the like. If it's 
public, it should be known.

> 
> How annoying would it be to show links to all modules that a module publicly 
> imports? That would be useful.

Another good suggestion, it can be done.

> 
> Some classes and modules are very big, a (clickable) summary of sorts would 
> be nice. See tango.text.Util for example where this has been done manually 
> for all the function templates.

I can see that summary is in the ddoc of the module. It's not generated 
by the documentation generator.

But a summary of a module is a must. I want this to also look like 
Javadoc, where first you have "field summary", "constructor summary", 
etc., with links to their description. This makes it easier to find 
something very quickly.

But... a module is much bigger than a Java class. So maybe I'll import 
jquery and just show every member collapsed, and then you'll be able to 
expand it.

I see if this doesn't slow a lot the documentation browsing. (I don't 
think jquery is very heavy-weight, specially since it comes minified, 
and I've used it and it's fast). Browsing the Tango documentation is 
kind of slow, it takes like 3 seconds to open a module after I click it, 
I don't know why. So I want the documentation browsing to be fast.

> 
> Do you know Natural Docs? It has a pretty good though sometimes a little  
> verbose  presentation of generated docs (also does summaries): 
> http://www.naturaldocs.org/documentation/html/files/NaturalDocs-.html
> 
> Especially the indexing bits are very good.

I'll take a look at it and see how can it inspire me. :-)

Thanks for the good suggestions, Lutger.