Descent generated documentation

[Gide Nwawudu]

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

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