Descent generated documentation

[Ary Borenszweig]

Jacob Carlborg escribió:
> 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

As I answered to Lutger, I'll probably just allow you to expand/collapse 
things, and everything will be collapsed by default, so it'll be like a 
summary.

> Generated source code like the tango documentation has

Why would you like to see the source code? I never seen this "feature" 
in any other documentation generator. One should not need to see the 
source code to use the API.

If a lot of people request it, I'll do it. But I don't like to break 
encapsulation, even in documentation! :-P

> Show all inherited methods in the subclass, only as links

Good one. This is also done by Javadoc. I'll do it.

I'll also provide a link for the method overrided by a method, if any. 
(again, like in Javadoc)