Descent generated documentation

[Steven Schveighoffer]

On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig <ary at 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