Summary: | better integration of code and documentation | ||
---|---|---|---|
Product: | [Applications] kdevelop | Reporter: | Sphere <sphere1952> |
Component: | general | Assignee: | KDevelop Developers <kdevelop-devel> |
Status: | RESOLVED FIXED | ||
Severity: | wishlist | ||
Priority: | NOR | ||
Version: | git master | ||
Target Milestone: | --- | ||
Platform: | Compiled Sources | ||
OS: | Linux | ||
Latest Commit: | Version Fixed In: |
Description
Sphere
2003-06-18 20:24:10 UTC
You want Doxygen: http://www.doxygen.org Look at KDE's source code and .h files. That's how we generate the documentation. Besides, since KDevelop uses KDE's common admin/ tree, it boils down to: 1) adding "include $(topsrcdir)/Doxyfile.am" in your Makefile.ams 2) you writing the documentation. 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@mail.com 2003-06-18 21:25 ------- >You want Doxygen: http://www.doxygen.org > >Look at KDE's source code and .h files. That's how we generate the >documentation. Besides, since KDevelop uses KDE's common admin/ tree, it >boils down to: >1) adding "include $(topsrcdir)/Doxyfile.am" in your Makefile.ams >2) you writing the documentation. > > > Bad answer. Making the user do things sucks. Make the code smarter instead. 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@mail.com 2003-06-18 21:25 ------- >You want Doxygen: http://www.doxygen.org > >Look at KDE's source code and .h files. That's how we generate the >documentation. Besides, since KDevelop uses KDE's common admin/ tree, it >boils down to: >1) adding "include $(topsrcdir)/Doxyfile.am" in your Makefile.ams >2) you writing the documentation. > > > Besides, you don't get my point. I don't want documentation on how to use the code. I want documentation on what's going on in the code. The only way that's ever going to happen is if people can add to it while debugging. This is the only time people are thinking about what's really going on, and then they'll document only because they don't want to have to find their way from twiddle 1 to twiddle 2 again. 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. 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@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. When you add comments (read: doxygen documentation/directives) during debugging, the breakpoints stay in their place. So basicaly there is no reason to not add documentation while you're debugging. |