Descent generated documentation

[Ary Borenszweig]

Steven Schveighoffer wrote:
> 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.

Ok, I'll provide an option then.