12:55 p.m.
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.
3:14 p.m.
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
12:45 a.m.
New subject: Trace Bitmap - SIOX Foreground Selection
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?
--
Andrew
12:58 a.m.
New subject: Trace Bitmap - SIOX 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
1:29 a.m.
New subject: Trace Bitmap - SIOX Foreground Selection
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
--
Andrew
6:04 a.m.
-----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
4:07 p.m.
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.
--
Andrew
4:27 p.m.
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)
...
4:43 a.m.
-----Original Message-----
From: Jon Cruz [mailto:jon@...18...]
Sent: woensdag 23 maart 2011 8:27
To: rugby471@...400...
Cc: inkscape-devel(a)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
11:13 a.m.
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.
5:24 a.m.
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
12:02 p.m.
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
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
Handy.
2. Use /** */ and /// instead of /*! */ and //!
Yes, very much so. Among other things that keeps doc comments simple and consistent.
3. 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)
4. 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.
4:56 a.m.
-----Original Message-----
From: Jon Cruz [mailto:jon@...18...]
Sent: donderdag 24 maart 2011 4:03
To: Krzysztof Kosiński
Cc: inkscape-devel(a)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
4446
days inactive
4455
days old
inkscape-devel@lists.inkscape.org
12 comments
6 participants
participants (6)
-
Andrew -
Johan Engelen -
Jon Cruz -
Krzysztof Kosiński -
Tavmjong Bah -
~suv