Hello, just to announce that I committed source documentation changes to several dozen files. People are likely to recompile a lot but you know such things happen after new releases :]
There are two doxygen config files in the distribution: src/inkscape.doxygen (used for the web pages) and src/Doxygen. The latter is specific for some files in order to be able to quickly check correctness or missing documentation.
My goal for the next release is to have one-liners for all classes and functions in the source files referred to by src/Doxygen.
In this regard, I will introduce \note, \todo, and \bug tags in comments, and I would ask people to use them for their own documentation, too. \todo's for example will be collected in a todo file by doxygen. \bug's should be moved into the tracker, eventually, probably.
Finally, I noticed people use 'e.g.' and 'i.e.' incorrectly: you should not forget to always place a comma after them, i.e., e.g., like this. Reason: doxygen thinks the sentence ended there.
ralf
On 7/25/05, Ralf Stephan <ralf@...748...> wrote:
Hello, just to announce that I committed source documentation changes to several dozen files. People are likely to recompile a lot but you know such things happen after new releases :]
Cool, why won't you document that in Internal Progress here:
http://inkscape.org/cgi-bin/wiki.pl?ReleaseNotes
I really hope developers will be more forthcoming in documenting their progress for this release. If you don't have time to describe your contribution fully, at least leave a placeholder in [].
On Mon, Jul 25, 2005 at 12:39:28PM -0300, bulia byak wrote:
On 7/25/05, Ralf Stephan <ralf@...748...> wrote:
Hello, just to announce that I committed source documentation changes to several dozen files. People are likely to recompile a lot but you know such things happen after new releases :]
Cool, why won't you document that in Internal Progress here:
http://inkscape.org/cgi-bin/wiki.pl?ReleaseNotes
I really hope developers will be more forthcoming in documenting their progress for this release. If you don't have time to describe your contribution fully, at least leave a placeholder in [].
In addition, some people are not recording their changes in ChangeLog. I had tried to help fill out the ReleaseNotes based on comments in ChangeLog, but the information was not there either.
Bryce
On Mon, Jul 25, 2005 at 04:57:33PM +0200, Ralf Stephan wrote:
Hello, just to announce that I committed source documentation changes to several dozen files. People are likely to recompile a lot but you know such things happen after new releases :]
There are two doxygen config files in the distribution: src/inkscape.doxygen (used for the web pages) and src/Doxygen. The latter is specific for some files in order to be able to quickly check correctness or missing documentation.
My goal for the next release is to have one-liners for all classes and functions in the source files referred to by src/Doxygen.
Excellent! This will be quite helpful going forward.
In this regard, I will introduce \note, \todo, and \bug tags in comments, and I would ask people to use them for their own documentation, too. \todo's for example will be collected in a todo file by doxygen. \bug's should be moved into the tracker, eventually, probably.
This is great, I wonder if it'd be possible to make a script to convert // TODO items over to \todo ?
Also, yesterday I learned of the existance of some tools that automate production of unit test stubs based on Doxygen items. Basically I think they set up the code to invoke the given function, and if you've documented the function's parameters, it sets up the calling syntax to test them out. It's called "Doclet" IIRC.
Anyway, I think your efforts may pay off double, if/when we do that. :-)
Bryce
participants (3)
-
Bryce Harrington -
bulia byak -
Ralf Stephan