First of all, is anyone using our doxygen docs, or does anyone care about the format?
Our current usage is a bit inefficient, so I've been thinking of cleaning it up a bit. First on the hit list are those annoying "@brief" instances.
Or config file has this:
# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen # will interpret the first line (until the first dot) of a JavaDoc-style # comment as the brief description. If set to NO, the JavaDoc # comments will behave just like regular Qt-style comments # (thus requiring an explicit @brief command for a brief description.)
JAVADOC_AUTOBRIEF = YES
So that means instead of :
/** * @brief XML - prefs observer bridge * * This is an XML node observer that watches for changes in the XML document storing the preferences. * It is used to implement preference observers. */
We can do:
/** * XML - prefs observer bridge. * * This is an XML node observer that watches for changes in the XML document storing the preferences. * It is used to implement preference observers. */
The key point is to just have a single period so that the first sentence *is* the brief description. No need for additional work or @ tags.
On 21/3/11 04:55, Jon Cruz wrote:
First of all, is anyone using our doxygen docs, or does anyone care about the format?
Currently, the doxygen documentation can be viewed online at
http://inkscape.modevia.com/doxygen/html/
@Inc, @ChrisMorgan - are there any plans to integrate the doxygen docs into the new web site?
Does anyone know if the current setup on modevia is based on current inkscape trunk or on the latest stable release branch (0.48.x)?
~suv
Hi All,
Regarding some work I may do on the Trace Bitmap dialog, what does checking the 'SIOX foreground selection' checkbox actually do? And how do you go about using the foreground selection?
On Wed, 2011-03-30 at 16:45 +0100, Andrew wrote:
Hi All,
Regarding some work I may do on the Trace Bitmap dialog, what does checking the 'SIOX foreground selection' checkbox actually do? And how do you go about using the foreground selection?
See:
http://tavmjong.free.fr/INKSCAPE/MANUAL/html/Trace-SIOX.html
On 30/03/11 16:58, Tavmjong Bah wrote:
On Wed, 2011-03-30 at 16:45 +0100, Andrew wrote:
Hi All,
Regarding some work I may do on the Trace Bitmap dialog, what does checking the 'SIOX foreground selection' checkbox actually do? And how do you go about using the foreground selection?
See:
http://tavmjong.free.fr/INKSCAPE/MANUAL/html/Trace-SIOX.html
Thanks
-----Original Message----- From: Jon Cruz [mailto:jon@...18...] Sent: maandag 21 maart 2011 4:56
First of all, is anyone using our doxygen docs, or does anyone care about the format?
Yes, I care about doxygen, and a little bit about the format. In any case, I think the 'standard' of how to write documentation should be clear to someone who starts writing documentation. For me, it is always a struggle to find a good example in Inkscape's code of how it should be done. For example, how to document a function, specifying what the arguments mean, and what is returned.
I do not care in particular what format is settled on. Although I think the '@brief' does no harm, and don't see the benefit of going to the trouble of deleting it.
Ciao, Johan
On 22/03/11 21:04, Johan Engelen wrote:
-----Original Message----- From: Jon Cruz [mailto:jon@...18...] Sent: maandag 21 maart 2011 4:56
First of all, is anyone using our doxygen docs, or does anyone care about the format?
Yes, I care about doxygen, and a little bit about the format. In any case, I think the 'standard' of how to write documentation should be clear to someone who starts writing documentation. For me, it is always a struggle to find a good example in Inkscape's code of how it should be done. For example, how to document a function, specifying what the arguments mean, and what is returned.
I agree, currently I am doing some quite major work to the OCAL dialog code, and it would be helpful if there was a page on the wiki (if it doesn't already exist) with a good example of how to format the comments etc.
On Mar 23, 2011, at 12:07 AM, Andrew wrote:
On 22/03/11 21:04, Johan Engelen wrote:
-----Original Message----- From: Jon Cruz [mailto:jon@...18...] Sent: maandag 21 maart 2011 4:56
First of all, is anyone using our doxygen docs, or does anyone care about the format?
Yes, I care about doxygen, and a little bit about the format. In any case, I think the 'standard' of how to write documentation should be clear to someone who starts writing documentation. For me, it is always a struggle to find a good example in Inkscape's code of how it should be done. For example, how to document a function, specifying what the arguments mean, and what is returned.
I agree, currently I am doing some quite major work to the OCAL dialog code, and it would be helpful if there was a page on the wiki (if it doesn't already exist) with a good example of how to format the comments etc.
Yes. Hopefully I'll be able to get that together. Some start might be good if anyone wants to jump in and just stub some things out.
* start with "/**" * have the first sentence as a brief description, and be sure to end with a period '.' * comment a function/method in the .h and not the .cpp (if it is in both) ...
-----Original Message----- From: Jon Cruz [mailto:jon@...18...] Sent: woensdag 23 maart 2011 8:27 To: rugby471@...400... Cc: inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] Doxygen cleanup
[snip]
- comment a function/method in the .h and not the .cpp (if it
is in both) ...
Nota bene? I thought we'd rather have the comments in the .cpp, such that recompilation is much faster?
I forgot to mention that 2geom has some good examples of simple and advanced use of doxygen. Krzysztof did a good job documenting many methods and other 2geom details.
Ciao, Johan
On Mar 23, 2011, at 12:43 PM, Johan Engelen wrote:
Nota bene? I thought we'd rather have the comments in the .cpp, such that recompilation is much faster?
No, that placement does not really affect compilation times.
The main factor there is when you *change* documentation in a .h file. Then you cause files that have included it to be rebuilt.
Of course there are a few mitigating factors:
* One should not be changing documentation by itself very often. Thus doc cleanups won't carry a significant impact.
* By the time an average dev pulls a doc-only change, the chance is that he's also pulled other changes that will trigger rebuilds anyway. (we also have some nasty too-wide-ranging .h files that often trigger this)
* Header files should avoid including other header files (forward declarations, etc., can replace most #including). Thus the impact of any given change is lessened)
Bottom line is that merely being present in a .h file does not affect compilation times in any significant manner.
2011/3/23 Jon Cruz <jon@...18...>:
- start with "/**"
- have the first sentence as a brief description, and be sure to end with a period '.'
- comment a function/method in the .h and not the .cpp (if it is in both)
...
Documenting in the .h is contentious. My opinion is: if the function is defined only in the header (inline), put the docs in the header. But if it's defined in .cpp, put the docs above the definition in .cpp, so documentation changes won't trigger extensive recompiles.
I would add 1. If there is a @file comment at the top, do not include the author information in it - put it in a separate normal comment 2. Use /** */ and /// instead of /*! */ and //! 3. For one-line documentation of class members, use ///< after the member 4. Be careful to document what you are intending to, not e.g. the Inkscape namespace
Regards, Krzysztof
On Mar 23, 2011, at 1:24 PM, Krzysztof Kosiński wrote:
2011/3/23 Jon Cruz <jon@...18...>:
- start with "/**"
- have the first sentence as a brief description, and be sure to end with a period '.'
- comment a function/method in the .h and not the .cpp (if it is in both)
...
Documenting in the .h is contentious. My opinion is: if the function is defined only in the header (inline), put the docs in the header. But if it's defined in .cpp, put the docs above the definition in .cpp, so documentation changes won't trigger extensive recompiles.
Not really. It hasn't been contentious in professional development for some time now.
First it only affects incremental builds, so that mainly leaves it to potentially affecting individual developers or incremental build systems. However the latter are usually automated and happily run often, so they don't care. And for developers, one would have to pull only the doc change and no other changes. For most any project with a noticeable velocity this is a rare occurrence.
More important is that such doc-only changes are extremely rare (perhaps once a quarter, if even that frequently). On the other hand the .h file is the public documentation of the corresponding compilation units, and should be kept in sync. One should be able to read just the .h and know how to use the code. Modularity and encapsulation are key to good modern software development (Brooks explains this well in his 20-year follow up to The Mythical Man Month), and keeping the .h to declare and the .cpp to define are main contributors to good encapsulation. Sacrificing things such as legibility and maintainability for the rare boost to odd builds is usually not worth it.
On the other hand, docs should be updated each and every time functions and methods change. Having them right next to each other aid in this maintainability and overall legibility. Professional developers have also found that having doc comments in the .cpp files leads more often to them becoming stale and outdated.
Also, a function or method declaration is a promise to others about the behavior of the code. Formalizing such promises with corresponding documentation is a very good thing. Developing habits to formalize promises early and to avoid arbitrary changes to the substance of a promise is also a very good thing.
I would add
- If there is a @file comment at the top, do not include the author
information in it - put it in a separate normal comment
Handy.
- Use /** */ and /// instead of /*! */ and //!
Yes, very much so. Among other things that keeps doc comments simple and consistent.
- For one-line documentation of class members, use ///< after the member
Yes (though I find this most useful for short comments. For longer ones a normal /** */ might be warranted. But there are usually less of those cases)
- Be careful to document what you are intending to, not e.g. the
Inkscape namespace
Quite important. I find it most useful to run a doxygen pass after doing some changes, and making sure what I thought I was doing actually shows up properly.
-----Original Message----- From: Jon Cruz [mailto:jon@...18...] Sent: donderdag 24 maart 2011 4:03 To: Krzysztof Kosiński Cc: inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] Doxygen cleanup
On Mar 23, 2011, at 1:24 PM, Krzysztof Kosiński wrote:
2011/3/23 Jon Cruz <jon@...18...>:
- start with "/**"
- have the first sentence as a brief description, and be
sure to end with a period '.'
- comment a function/method in the .h and not the .cpp (if
it is in
both) ...
Documenting in the .h is contentious. My opinion is: if the
function
is defined only in the header (inline), put the docs in the header. But if it's defined in .cpp, put the docs above the definition in .cpp, so documentation changes won't trigger extensive recompiles.
Not really. It hasn't been contentious in professional development for some time now.
First it only affects incremental builds, so that mainly leaves it to potentially affecting individual developers or incremental build systems. However the latter are usually automated and happily run often, so they don't care. And for developers, one would have to pull only the doc change and no other changes. For most any project with a noticeable velocity this is a rare occurrence.
More important is that such doc-only changes are extremely rare (perhaps once a quarter, if even that frequently). On the other hand the .h file is the public documentation of the corresponding compilation units, and should be kept in sync. One should be able to read just the .h and know how to use the code. Modularity and encapsulation are key to good modern software development (Brooks explains this well in his 20-year follow up to The Mythical Man Month), and keeping the .h to declare and the .cpp to define are main contributors to good encapsulation. Sacrificing things such as legibility and maintainability for the rare boost to odd builds is usually not worth it.
On the other hand, docs should be updated each and every time functions and methods change. Having them right next to each other aid in this maintainability and overall legibility. Professional developers have also found that having doc comments in the .cpp files leads more often to them becoming stale and outdated.
Also, a function or method declaration is a promise to others about the behavior of the code. Formalizing such promises with corresponding documentation is a very good thing. Developing habits to formalize promises early and to avoid arbitrary changes to the substance of a promise is also a very good thing.
I think comparing Inkscape development with professional development is quite a stretch. Even if people are going to document stuff in Inkscape, it is most probably done incrementally (like much else), because it is more 'fun' this way. And I really hope nobody is going to start documenting verbs.h incrementally. I have additional arguments in favor of putting comments in the .cpp files. For me, it helps sometimes to see the documentation of a function next to its code; helps noticing bugs. While comments in a header file sometimes bloat the file and make it pretty hard to find a method that I want to call (sp-object.h is a horrible read, whatever experts say, I don't like it). The good thing about us using doxygen syntax is that... one can run doxygen (!) and read comments in a reader friendly interface. So one really shouldn't look at the code files to read documentation, right?
Ciao, Johan
participants (6)
-
Andrew -
Johan Engelen -
Jon Cruz -
Krzysztof Kosiński -
Tavmjong Bah -
~suv