[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: Experiences of Doxygen's @copydoc tag: good or bad?
From:       Frans Englich <frans.englich () telia ! com>
Date:       2005-09-23 20:33:27
Message-ID: 200509232033.27879.frans.englich () telia ! com
[Download RAW message or body]

On Friday 23 September 2005 19:54, Adriaan de Groot wrote:
> On Friday 23 September 2005 21:26, Frans Englich wrote:
> > Doxygen have the tag @copydoc which copies the comments of another
> > function(or similar) and places it where the tag is. My instant thought
> > is that it would be practical cases where one have many sub-classes of
> > central abstract base classes.
>
> Except that for virtual methods, the documentation is _already_ duplicated.

And in my case it is exactly virtual functions(pure in most cases, even). I 
did some grepping in my specific project, the XPath 2.0 code in 
work/branches/kdom/xpath, and for one area I have about 80 classes which all 
implement more or less one or two functions. Even if it was the right thing 
to write individual documentation for these functions it would be a massive 
task, and I doubt whether it is, since these re-implemented functions aren't 
indiviualized in a way appropriate to mention in the API docs. I'll assume 
your recommendations in your letter holds for this case too.

I have another Doxygen question: I would like to complement the docs with 
pretty conceptual drawings and schematics. Does people have good experiences 
with Umbrello for this, or are there other preferences? (I presume @image is 
straightforward for this after exporting to an appropriate format.)


Cheers,

		Frans

> The following example:
>
> /** Class to represent a kind of animal. */
> class Animal {
>   public:
>     /** Breed. @return number of kids. */
>     virtual int breed() = 0;
>     /** Perish. Hope you called breed() before. */
>     void die();
> } ;
>
> /** A Moose is a kind of animal. */
> class Moose : public Animal {
>   public:
>     int breed();
>     void die();
> } ;
>
> The dox for Moose contain the explanations from Animal just as you might
> expect. Other things that are copied are parameter dox in subclass
> reimplementations of methods, which is why Doxygen complains if you rename
> parameters in reimplementations.
>
> > One can also pose an ultimatum which unfortunately is relevant for my
> > code in question: should one leave functions undocumented, or copy from
> > the base class? Which one is the lesser evil?
>
> Leave undocumented and let Doxygen do the copying itself (at least, for the
> subclass case you describe above); if you believe that the header file
> itself should be the final source of information, cut and paste, don't use
> @copydoc.
>
> For the purposes of handling convenience methods, I would use @copydoc.
> That may render weirdly, though.
 
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<

[prev in list] [next in list] [prev in thread] [next in thread]