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. :-)

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)

I assume you plan to do something with visibility?

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

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.

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.

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

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.

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)

On Thu, 09 Jul 2009 10:18:37 -0400, Ary Borenszweig <ary@esperanto.org.ar> wrote:

> 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).

:O  Wow, just wow.

I am very impressed, it already looks like something I'd much rather have than the current docs.

Looking at the Tango docs, there are a lot of empty/sparse pages, it looks like you aren't capturing struct methods, is that the only reason?

>> 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)

er... please copy base documentation, don't link.  You can put "inherited from BaseClass.basemethod".

Reason being, I want to know how object X behaves, I don't want to have to care where it inherited its guts from, and I also don't want to click 20 times to read all the doc for one object.

Looks like I have to try and figure out how to install descent again :)

-Steve

Steven Schveighoffer Wrote:

> On Thu, 09 Jul 2009 10:18:37 -0400, Ary Borenszweig <ary@esperanto.org.ar> wrote:
> 
> > 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).
> 
> :O  Wow, just wow.

:-)

> I am very impressed, it already looks like something I'd much rather have than the current docs.
> 
> Looking at the Tango docs, there are a lot of empty/sparse pages, it looks like you aren't capturing struct methods, is that the only reason?
> 
> >> 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)
> 
> er... please copy base documentation, don't link.  You can put "inherited
>  from BaseClass.basemethod".
> 
> Reason being, I want to know how object X behaves, I don't want to have to care where it inherited its guts from, and I also don't want to click 20 times to read all the doc for one object.

Yes, I´ll copy the docs from the base classes.

> Looks like I have to try and figure out how to install descent again :)

Note that this is in trunk, not in any release yet.

On Thu, 09 Jul 2009 14:05:26 -0400, Ary Borenszweig <ary@esperanto.org.ar> wrote:

> Note that this is in trunk, not in any release yet.


Don't worry, by the time I figure out how to do it, you'll have released it :P

-Steve

Reply to Steven,

> On Thu, 09 Jul 2009 14:05:26 -0400, Ary Borenszweig
> <ary@esperanto.org.ar>  wrote:
> 
>> Note that this is in trunk, not in any release yet.
>> 
> Don't worry, by the time I figure out how to do it, you'll have
> released  it :P
> 
> -Steve
> 

The way I do it on windows is quick and dirty:

- download "eclipse-cpp-galileo-win32.zip" from the C/C++ section here http://www.eclipse.org/downloads/
- unzip it somewhere
- download Descent's .zip file (I can't seem to find it, grrrr)
- unzip it on top of the first download
- run eclipse.exe

Ary Borenszweig wrote:
> phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/
> Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/

*drool*

I agree about the source code -- it's probably the main reason the Tango docs are so slow and it's useless 95% of the time. Doxygen can optionally generate source code in separate files and have links to it, which might be a good optional feature someday.