Doxygen statistics

[Tom]

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

 

[Öö Tiib]

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.

 

[Tom]

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.

 

[Öö Tiib]

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.

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.

 

[Jorgen Grahn]

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

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

 

[Gerhard Fiedler]

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