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.

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.

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.

Ary Borenszweig 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.

Regarding visibility, would it be onerous to have a switch somewhere that lets you produce "internal" documentation that shows private and protected members?

But this is quite cool; always nice to have another alternative.  :)

On Thu, 09 Jul 2009 20:01:02 -0300, 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.

It is helpful to read the source code, the unittests are enlightening. Unless there is an option to include unittests as example code in the documentation.

Gide

Daniel Keep wrote:
> But this is quite cool; always nice to have another alternative.  :)

What are the other alternatives? The interlinks are all but necessary for larger/OO projects.

Robert Fraser wrote:
> Daniel Keep wrote:
>> But this is quite cool; always nice to have another alternative.  :)
> 
> What are the other alternatives? The interlinks are all but necessary for larger/OO projects.

dmd and kandil.  I've used the Tango docs fairly well without the interlinks; it's a pain, yes.

Personally, I think DDoc is just plain wrong, but maybe that's just me.  :P

Gide Nwawudu escribió:
> On Thu, 09 Jul 2009 20:01:02 -0300, 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.
> 
> It is helpful to read the source code, the unittests are enlightening.
> Unless there is an option to include unittests as example code in the
> documentation.

Now that's a good idea!!

A lot of times unit tests show how an API is supposed to be used, and explains a lot more than documentation.

I'll definitely include unit tests in the documentation.

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

Daniel Keep escribió:
> 
> Ary Borenszweig 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.
> 
> Regarding visibility, would it be onerous to have a switch somewhere
> that lets you produce "internal" documentation that shows private and
> protected members?

It already works like that, you can select that in the UI that allows you to generate the documentation. :-)

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

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.

-Steve