[Bug 60015] better integration of code and documentation

[Sphere]

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
     
http://bugs.kde.org/show_bug.cgi?id=60015     




------- Additional Comments From sphere1952 at attbi.com  2003-06-18 22:34 -------
Subject: Re:  better integration of code and documentation

Thiago Macieira wrote:

>------- You are receiving this mail because: -------
>You reported the bug, or are watching the reporter.
>     
>http://bugs.kde.org/show_bug.cgi?id=60015     
>
>
>
>
>------- Additional Comments From thiagom at mail.com  2003-06-18 22:00 -------
>I disagree with "documentation" part, but I fully understand what you mean by 
>adding comments and notes to the code while debugging. Yes, it should be made 
>really easy. 
> 
>Documentation must be thought with care and I've found Doxygen to be a great 
>tool. For quick notes during the development process, I agree with you.
>
>  
>
There are many types of documentation.  Some documentation is for the tech
writers to work with.  Some documentation is for debugging.  Some 
documentation
is for the end user.  The more pieces of end user documentation you can 
get the
coder to write while debugging the better, but you're never going to get 
very
much.

Best you can hope for is getting whatever you can out of the coder while 
they're
working on the code and then transform it into end-user docs.  If 
doxygen can
help tease some info out of the coder then it's a step in the right 
direction, but
you really want the system set up in such a way that it's hard for the 
coder not
to provide some information -- and for the most part the only time 
they're going
to do the providing is while they're deep in the middle of the code.

(How many times have you read nice little descriptions at the top of a 
file which
have little or nothing to do with what the code really is?  These nice 
little descriptions
are generally worse than no coment at all.)

Sphere.