Descent generated documentation

Ary Borenszweig ary at esperanto.org.ar
Wed Jul 8 21:44:41 PDT 2009


Hi all!

So... I've been playing around with generating ddocs from Descent. I 
wanted several things:

1. Each reference to a symbol has a link to it. This applied to field 
types, functions and methods return types and parameters.
2. Get to know the supertype hierarchy of a given class.
3. Get to know direct subclasses of a given class.
4. Get to know all interfaces a class implements.
6. Show documentation for compile-time code.
7. You didn't see I skipped the number 5 in the list.

(a little joke for the last point :-P)

I already implemented 1, 2, 3, 4, and 6 is really easy with what I have 
now (but I don't want to do it now).

Before giving comments about the documentation I'll show you, please 
don't judge colors, appeareance, etc. All of that can be changed. This 
is just a proof of concept of how I think documentation of APIs should 
look like.

(I have to admit I was inspired, a lot, by Javadoc)

Templates don't appear in this documentation because I'm lazy. Also I 
might have skipped the module documentation (should appear at the top), 
and enum members. And I don't respect visibility, I show everything. I 
just want to know opinions about this before continuing working on this, 
maybe later nobody uses it or find it useful. [1]

So... here are the (partial) documentations for phobos and tango.

phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/
Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/

(I recommend seeing std.stream in phobos, and tango.io.Buffer to see 1, 
2, 3 and 4 in effect).


[1] Like... The Tango developers, or phobos team might say "Oh, the 
documentation generation can't be automated in our scripts? We have to 
open Eclipse for that? I know it's better than ddoc or dil, we just 
don't care, our build process is important here". Before saying that, 
remember the end-user of your API doesn't care about your build process, 
she just want to use your API in the best and fastest possible there is. :-)


More information about the Digitalmars-d-announce mailing list