[bind10-dev] Reused parameters & doxygen

[JINMEI Tatuya / 神明達哉]

At Tue, 20 Dec 2011 17:28:50 +0100,
Michal 'vorner' Vaner <michal.vaner at nic.cz> wrote:

> We had a little disagreement about what is the right thing to do, when one
> function acts mostly the same as another function, and takes similar/same
> parameters.
> 
> I just wrote „this function works like the other, including parameters, with
> these differences“. I believe it is the best thing to do, because the code is
> like that, and if the code of first function changed, it would change the
> behaviour of the second. But if we had two copies of the documentation, we could
> forget to update it.

I agree.  I'm a strong supporter of the "Don't Repeat Yourself" principle.

> However, it produces warnings from doxygen, which I
> personally believe to be a bug of doxygen (it is true the parameters aren't
> explicitly described, but following the warnings only makes the documentation
> needlessly beurocratic and repetitive).
> 
> So, what do you think is the right way to solve this?

For a shorter term, I'd suggest just ignoring the warning (right now
we are not requesting it should be warning free, right?).  For a bit
longer term, maybe we should research into doxygen details to see
whether there is a filter or something to make exception.  For a much
longer term we might write a patch to doxygen and propose it:-)

---
JINMEI, Tatuya
Internet Systems Consortium, Inc.