Doxygen statistics

Discussion in 'C++' started by Tom, Apr 24, 2011.

  1. Tom

    Tom Guest

    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
    Tom, Apr 24, 2011
    #1
    1. Advertising

  2. Tom

    Öö Tiib Guest

    On Apr 24, 2:38 pm, Tom <> 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.
    Öö Tiib, Apr 24, 2011
    #2
    1. Advertising

  3. Tom

    Tom Guest

    On 24 Apr., 21:52, Öö Tiib <> wrote:
    > On Apr 24, 2:38 pm, Tom <> 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.
    Tom, Apr 25, 2011
    #3
  4. Tom

    Öö Tiib Guest

    On Apr 25, 10:29 pm, Tom <> wrote:
    > On 24 Apr., 21:52, Öö Tiib <> wrote:
    >
    >
    >
    >
    >
    > > On Apr 24, 2:38 pm, Tom <> 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.
    Öö Tiib, Apr 26, 2011
    #4
  5. Tom

    Jorgen Grahn Guest

    On Mon, 2011-04-25, Tom wrote:
    > On 24 Apr., 21:52, Öö Tiib <> wrote:
    >> On Apr 24, 2:38 pm, Tom <> 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 .
    Jorgen Grahn, Apr 27, 2011
    #5
  6. 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
    Gerhard Fiedler, Apr 28, 2011
    #6
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Karthik
    Replies:
    0
    Views:
    395
    Karthik
    Apr 29, 2004
  2. Karthik
    Replies:
    0
    Views:
    627
    Karthik
    Apr 29, 2004
  3. JasonDamianUs

    Doxygen Question - method body missing

    JasonDamianUs, Dec 27, 2005, in forum: Java
    Replies:
    0
    Views:
    369
    JasonDamianUs
    Dec 27, 2005
  4. Guillaume Brocker

    [Announcement] Doxygen frontend for Eclipse

    Guillaume Brocker, Feb 5, 2004, in forum: C++
    Replies:
    0
    Views:
    5,312
    Guillaume Brocker
    Feb 5, 2004
  5. Mike Wahler

    Re: [OT] Namespace and doxygen

    Mike Wahler, Feb 28, 2004, in forum: C++
    Replies:
    2
    Views:
    480
    Mike Wahler
    Feb 28, 2004
Loading...

Share This Page