Version: (using KDE Devel) Installed from: Compiled sources I want to be able to enter notes/comments/documentation-parts anywhere in my source, even if it means adding an extra layer before the compilier with my source embedded in an HTML (or whatever) file. It would also be nice to be able to highlight parts of my source and do the other sorts of things you can do in HTML but not in ASCII. This could be done with a separate database, but I bet it would break on a regular basis. Working with a file which needed a preprocessing step in order to strip out the non-source data is less likely to break. (I do mean anywhere. One of the most important things I want to be able to add is a pointer from the use of a variable to some other part of the code which would not be reached by any obvious source traversal. This would require adding both the URL and a destination tag.)
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.