On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig <ary@esperanto.org.ar> wrote:

> Ary Borenszweig escribió:
>> Hi all!
>>  So... I've been playing around with generating ddocs from Descent.
>>  phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/
>> Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/
>
> I've updated the docs. New things:
>
> - Visibility is respected
> - Everything except templates are listed (also nested types are listed)
> - Modifiers are shown
> - Public imports are listed (but it doesn't work quite well, I'll check it)
> - Module level documentation is shown
> - Inherited methods are shown
>
> Still no expand/collapse thingy.

/me cleans up pool of drool on desk.

One preference, if it's possible, is to copy the description of inherited methods from the base class.  Even if not the entire documentation, just a summary, first sentence from the documentation.

Already it's better than ddoc.  Nice work!

-Steve

Steven Schveighoffer wrote:
> On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig <ary@esperanto.org.ar> wrote:
> 
>> torhu escribió:
>>> On 09.07.2009 16:18, Ary Borenszweig wrote:
>>>> Jacob Carlborg escribió:
>>>>>  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
>>>>
>>>  Especially with Tango I've found that it's often easier to figure out what you need to know by reading the code than the docs.  Particularly Kris' code for some modules is easier to read than the (current and previous) docs, and in some cases the code will always tell you more than docs can.  So it would be nice to have a link to the source.  Just a link to the plain text version would be perfect.
>>
>> Then better docs should be written. :-)
>>
>> Looking at the source code tempts you to do dirty things. I don't want that happenning.
> 
> Having a link to the source code is helpful for clarification, especially when you didn't write the documentation.  Not all developers have teams of people writing comprehensive documentation like Microsoft or Sun :)
> 
> Most tools have the ability to generate source files in HTML, including javadoc and doxygen.  Not doing it by default is fine, but don't assume it's a worthless option.

Ok, I'll provide an option then.

On 10.07.2009 14:41, Ary Borenszweig wrote:
> You can select the maximum visibility: private, protected or public.
>
> (in the original UI in the plugin for Java there's also "package",
> but... where does "package" fall? private<  package<  protected?
> protected<  package<  public? I think neither, mmm...)

I'd say the first order is right.  package is 'private to the library', but protected is available in subclasses everywhere.

Hello Ary,

> (unfortunately the listing will be "unit test 1", "unit test 2", etc.,
> because there's no way to name unit tests, grrrrrrrrrr....)
> 


/// General usage
unittest { ... }


/// Multi threaded usage
unittest { }

.
.
.

Cool, can you do preconditions and class invariants too?

Lutger wrote:
> Cool, can you do preconditions and class invariants too?

Sure.

Steven Schveighoffer wrote:
> On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig <ary@esperanto.org.ar> wrote:
> 
>> Ary Borenszweig escribió:
>>> Hi all!
>>>  So... I've been playing around with generating ddocs from Descent.
>>>  phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/
>>> Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/
>>
>> I've updated the docs. New things:
>>
>> - Visibility is respected
>> - Everything except templates are listed (also nested types are listed)
>> - Modifiers are shown
>> - Public imports are listed (but it doesn't work quite well, I'll check it)
>> - Module level documentation is shown
>> - Inherited methods are shown
>>
>> Still no expand/collapse thingy.
> 
> /me cleans up pool of drool on desk.
> 
> One preference, if it's possible, is to copy the description of inherited methods from the base class.  Even if not the entire documentation, just a summary, first sentence from the documentation.
> 
> Already it's better than ddoc.  Nice work!
> 
> -Steve

me too

Also, I think Javadoc's tables are easier to read. The "list" view of this looks better, but it's difficult to differentiate what is what. Javadoc's tables & lines give a clear separation between sections. Just my bikeshed.

Robert Fraser wrote:
> Steven Schveighoffer wrote:
>> On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig <ary@esperanto.org.ar> wrote:
>>
>>> Ary Borenszweig escribió:
>>>> Hi all!
>>>>  So... I've been playing around with generating ddocs from Descent.
>>>>  phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/
>>>> Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/
>>>
>>> I've updated the docs. New things:
>>>
>>> - Visibility is respected
>>> - Everything except templates are listed (also nested types are listed)
>>> - Modifiers are shown
>>> - Public imports are listed (but it doesn't work quite well, I'll check it)
>>> - Module level documentation is shown
>>> - Inherited methods are shown
>>>
>>> Still no expand/collapse thingy.
>>
>> /me cleans up pool of drool on desk.
>>
>> One preference, if it's possible, is to copy the description of inherited methods from the base class.  Even if not the entire documentation, just a summary, first sentence from the documentation.
>>
>> Already it's better than ddoc.  Nice work!
>>
>> -Steve
> 
> me too
> 
> Also, I think Javadoc's tables are easier to read. The "list" view of this looks better, but it's difficult to differentiate what is what. Javadoc's tables & lines give a clear separation between sections. Just my bikeshed.

It's not just bikeshed. It's important how the documentation looks, because you really just look at documentation and navigate it, nothing else. :)

I also though about the tables... but in Javadoc it's easier because each page lists all of the relevant information for a class, interface or enum. Here I have to list all the information for the modules. I could probably do some big sections, and then in each of them tables. Mmm... I'll see how it looks.

(tables are nice in Javadoc because you can scroll your eyes down and see the list of things, but in the current list of my docs you have the return type before it, and sometimes modifiers)

On Fri, 10 Jul 2009 10:05:38 -0400, Steven Schveighoffer <schveiguy@yahoo.com> wrote:

> One preference, if it's possible, is to copy the description of inherited methods from the base class.  Even if not the entire documentation, just a summary, first sentence from the documentation.
>
> Already it's better than ddoc.  Nice work!


More nitpicks:

You specify where a method is inherited from multiple times, i.e. tango.io.FileConduit inherits close from DeviceConduit, Conduit, and IConduit.  And methods overridden still list those methods as inherited.

1. Abstract methods aren't "Inherited", they are implemented, so abstract and interface methods shouldn't be listed as inherited methods.
2. Overridden methods aren't inherited, they are overridden, those should be listed differently.

All that would be easier, if all methods were listed inline with the appropriate attributions afterwards.  i.e.: (/italics/)

void close() /inherited from DeviceConduit/
uint write(void[] buf) /overrides DeviceConduit.write, implements OutputStream.write/

You must have expected this firestorm of requests :)  People have been complaining about the deficiencies of ddoc for a long time, but nobody's every really improved it.

-Steve

Steven Schveighoffer wrote:
> On Fri, 10 Jul 2009 10:05:38 -0400, Steven Schveighoffer <schveiguy@yahoo.com> wrote:
> 
>> One preference, if it's possible, is to copy the description of inherited methods from the base class.  Even if not the entire documentation, just a summary, first sentence from the documentation.
>>
>> Already it's better than ddoc.  Nice work!
> 
> 
> More nitpicks:
> 
> You specify where a method is inherited from multiple times, i.e. tango.io.FileConduit inherits close from DeviceConduit, Conduit, and IConduit.  And methods overridden still list those methods as inherited.
> 
> 1. Abstract methods aren't "Inherited", they are implemented, so abstract and interface methods shouldn't be listed as inherited methods.
> 2. Overridden methods aren't inherited, they are overridden, those should be listed differently.
> 
> All that would be easier, if all methods were listed inline with the appropriate attributions afterwards.  i.e.: (/italics/)
> 
> void close() /inherited from DeviceConduit/
> uint write(void[] buf) /overrides DeviceConduit.write, implements OutputStream.write/

I like it with italics afterwards. :)

Yes, I need to fix the duplicated inherited methods.

> 
> You must have expected this firestorm of requests :)  People have been complaining about the deficiencies of ddoc for a long time, but nobody's every really improved it.

But that's what this thread is about! I want comments about how documentation should be presented, and I already received a lot of good suggestions.