Descent generated documentation

Gide Nwawudu gide at btinternet.com
Fri Jul 10 00:42:17 PDT 2009


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


More information about the Digitalmars-d-announce mailing list