Descent generated documentation

[Jacob Carlborg]

On 7/9/09 6:44 AM, Ary Borenszweig wrote:
> 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.
> :-)

Very nice. A couple of things I want:
Some kind of summary
Generated source code like the tango documentation has
Show all inherited methods in the subclass, only as links