Descent generated documentation

[Ary Borenszweig]

Gide Nwawudu escribió:
> 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.

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