Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > C++ > Doxygen statistics

Reply
Thread Tools

Doxygen statistics

 
 
Tom
Guest
Posts: n/a
 
      04-24-2011
Hi NG,

I hope that I am not too much off topic with my question. We have C++
project which is badly documented. For a small fraction of the code
base there are already doxygen comments. We want to change this by
systematically documenting almost all code. The point now is that we
would like to measure the progress of this project. Is there a way to
get information out of doxygen to what degree the code is documented?
Or is there a way to list undocumented functions, classes, etc.?

Tom
 
Reply With Quote
 
 
 
 
Öö Tiib
Guest
Posts: n/a
 
      04-24-2011
On Apr 24, 2:38*pm, Tom <(E-Mail Removed)> wrote:
> Hi NG,
>
> I hope that I am not too much off topic with my question. We have C++
> project which is badly documented. For a small fraction of the code
> base there are already doxygen comments. We want to change this by
> systematically documenting almost all code. The point now is that we
> would like to measure the progress of this project. Is there a way to
> get information out of doxygen to what degree the code is documented?
> Or is there a way to list undocumented functions, classes, etc.?


You should establish what exactly and how should be documented in your
code-base. Then review your code and mark all places that need
documenting within code:

// TODO: document it

Such todo's are easy to count.

Beware that good documentation is not about quantity but about
quality. Too statistical -mechanical approaches often results with lot
of too useless doxygen comments like:

int listItemCount; ///< count of items in list.
color windowBackground; ///< color of window background.

That is easy to document for statistics-oriented mechanically-minded
documenter since he understands it without documentation.

Most unclear things often still remain undocumented because these are
the trickiest parts of code that no one fully understands.
 
Reply With Quote
 
 
 
 
Tom
Guest
Posts: n/a
 
      04-25-2011
On 24 Apr., 21:52, Öö Tiib <(E-Mail Removed)> wrote:
> On Apr 24, 2:38*pm, Tom <(E-Mail Removed)> wrote:
>
> > Hi NG,

>
> > I hope that I am not too much off topic with my question. We have C++
> > project which is badly documented. For a small fraction of the code
> > base there are alreadydoxygencomments. We want to change this by
> > systematically documenting almost all code. The point now is that we
> > would like to measure the progress of this project. Is there a way to
> > get information out ofdoxygento what degree the code is documented?
> > Or is there a way to list undocumented functions, classes, etc.?

>
> You should establish what exactly and how should be documented in your
> code-base. Then review your code and mark all places that need
> documenting within code:
>
> *// TODO: document it
>
> Such todo's are easy to count.


They are easy to count but not easy to add. A complete review of the
code would take much time, much more than I would like to spend just
to get some numbers on the documentation progress. Also this would
introduce lots of changes into the code base without having a real
benefit from it. After that merging branches would be a nightmare.

>
> Beware that good documentation is not about quantity but about
> quality. Too statistical -mechanical approaches often results with lot
> of too uselessdoxygencomments like:
>
> * int listItemCount; * * *///< count of items in list.
> * color windowBackground; ///< color of window background.
>
> That is easy to document forstatistics-oriented mechanically-minded
> documenter since he understands it without documentation.
>
> Most unclear things often still remain undocumented because these are
> the trickiest parts of code that no one fully understands.


That's right but I think we are able to distinguish between useful and
useless documentation. So I don't think that there is a risk of just
going for numbers. Numbers can also help focussing on the useful
documentation. Depending on the progress we see we might decide at
some point to spend some time on setting priorities.
 
Reply With Quote
 
Öö Tiib
Guest
Posts: n/a
 
      04-26-2011
On Apr 25, 10:29*pm, Tom <(E-Mail Removed)> wrote:
> On 24 Apr., 21:52, Öö Tiib <(E-Mail Removed)> wrote:
>
>
>
>
>
> > On Apr 24, 2:38*pm, Tom <(E-Mail Removed)> wrote:

>
> > > Hi NG,

>
> > > I hope that I am not too much off topic with my question. We have C++
> > > project which is badly documented. For a small fraction of the code
> > > base there are alreadydoxygencomments. We want to change this by
> > > systematically documenting almost all code. The point now is that we
> > > would like to measure the progress of this project. Is there a way to
> > > get information out ofdoxygento what degree the code is documented?
> > > Or is there a way to list undocumented functions, classes, etc.?

>
> > You should establish what exactly and how should be documented in your
> > code-base. Then review your code and mark all places that need
> > documenting within code:

>
> > *// TODO: document it

>
> > Such todo's are easy to count.

>
> They are easy to count but not easy to add. A complete review of the
> code would take much time, much more than I would like to spend just
> to get some numbers on the documentation progress. Also this would
> introduce lots of changes into the code base without having a real
> benefit from it.


First i said you should *establish* exactly what you want to document
in-code or otherwise. Lets say "each module should have description"
and "each class should have description". Then count your modules and
classes and there you have your number of defects. Only review can say
if one of such defects is fixed or not. What tool can estimate quality
of comments?

> After that merging branches would be a nightmare.


Adding some one-line comments to mark subtle defects causes merge
nightmares? In what repository? If you value your teams time then you
should migrate to better repository. Better ones import also the
history from old repositories.

>
> > Beware that good documentation is not about quantity but about
> > quality. Too statistical -mechanical approaches often results with lot
> > of too uselessdoxygencomments like:

>
> > * int listItemCount; * * *///< count of items in list.
> > * color windowBackground; ///< color of window background.

>
> > That is easy to document forstatistics-oriented mechanically-minded
> > documenter since he understands it without documentation.

>
> > Most unclear things often still remain undocumented because these are
> > the trickiest parts of code that no one fully understands.

>
> That's right but I think we are able to distinguish between useful and
> useless documentation.


Who "we"? You or the tool? You want a tool to count them, remember.

> So I don't think that there is a risk of just
> going for numbers. Numbers can also help focussing on the useful
> documentation. Depending on the progress we see we might decide at
> some point to spend some time on setting priorities.


There are three kinds of lies small lies, big lies and statistics. I
think it was Mark Twain.
 
Reply With Quote
 
Jorgen Grahn
Guest
Posts: n/a
 
      04-27-2011
On Mon, 2011-04-25, Tom wrote:
> On 24 Apr., 21:52, Öö Tiib <(E-Mail Removed)> wrote:
>> On Apr 24, 2:38*pm, Tom <(E-Mail Removed)> wrote:
>>
>> > Hi NG,

>>
>> > I hope that I am not too much off topic with my question. We have C++
>> > project which is badly documented. For a small fraction of the code
>> > base there are alreadydoxygencomments. We want to change this by
>> > systematically documenting almost all code. The point now is that we
>> > would like to measure the progress of this project. Is there a way to
>> > get information out ofdoxygento what degree the code is documented?
>> > Or is there a way to list undocumented functions, classes, etc.?


Don't know. Why isn't WARN_IF_UNDOCUMENTED followed by some
post-processing enough?

>> Beware that good documentation is not about quantity but about
>> quality. Too statistical -mechanical approaches often results with lot
>> of too uselessdoxygencomments like:
>>
>> * int listItemCount; * * *///< count of items in list.
>> * color windowBackground; ///< color of window background.
>>
>> That is easy to document forstatistics-oriented mechanically-minded
>> documenter since he understands it without documentation.
>>
>> Most unclear things often still remain undocumented because these are
>> the trickiest parts of code that no one fully understands.

>
> That's right but I think we are able to distinguish between useful and
> useless documentation. So I don't think that there is a risk of just
> going for numbers.


I get a bit suspicious, because IME people either focus on the right
things, or use numbers. Of course I can see the usefulness of numbers,
but it takes a lot of discipline to focus on doing the right thing,
when you can easily get that instant gratification from bumping the
documentation level from 20% to 40% by documenting the stuff that
doesn't need documentation.

> Numbers can also help focussing on the useful
> documentation. Depending on the progress we see we might decide at
> some point to spend some time on setting priorities.


How about a statistical approach, then? Have a script pick (say) 20
classes and 20 free functions at random, then manually inspect them
and extrapolate to the whole source code.

Otherwise, I agree with what Tiib wrote upthread (I haven't read what
he wrote downthread.)

/Jorgen

--
// Jorgen Grahn <grahn@ Oo o. . .
\X/ snipabacken.se> O o .
 
Reply With Quote
 
Gerhard Fiedler
Guest
Posts: n/a
 
      04-28-2011
Tom wrote:

> I hope that I am not too much off topic with my question. We have C++
> project which is badly documented. For a small fraction of the code
> base there are already doxygen comments. We want to change this by
> systematically documenting almost all code. The point now is that we
> would like to measure the progress of this project. Is there a way to
> get information out of doxygen to what degree the code is documented?
> Or is there a way to list undocumented functions, classes, etc.?


You can use something like EXTRACT_ALL and/or the various HIDE_UNDOC_...
configurations to create documentation of your documented code elements
and of all code elements, and then diff the two outputs. The diff
contains what's not yet documented.

Gerhard
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Doxygen Question - method body missing JasonDamianUs Java 0 12-27-2005 07:36 AM
Doxygen Task for Ant makefile maintainers Karthik Java 0 04-29-2004 11:40 AM
Doxygen Task for Ant makefile maintainers Karthik Java 0 04-29-2004 03:58 AM
Re: [OT] Namespace and doxygen Mike Wahler C++ 2 02-28-2004 06:18 PM
[Announcement] Doxygen frontend for Eclipse Guillaume Brocker C++ 0 02-05-2004 08:52 AM



Advertisments