[bind10-dev] doxygen warnings for lib/dns

[JINMEI Tatuya / 神明達哉]

At Wed, 3 Mar 2010 14:00:32 -0600 (CST),
"Jeremy C. Reed" <jreed at isc.org> wrote:

> > > trunk/src/lib/dns/cpp/rdataclass.cc:46: Warning: no matching class 
> > > member found for
> > >   isc::dns::rdata::in::AAAA::AAAA(const string &addrstr)
> > > Possible candidates:
> > >   isc::dns::rdata::in::AAAA::AAAA(const std::string &type_str)
> > >   isc::dns::rdata::in::AAAA::AAAA(InputBuffer &buffer, size_t rdata_len)
> > >   isc::dns::rdata::in::AAAA::AAAA(const AAAA &other)
> > 
> > is because in the definition file (.cc) the std name space is omitted
> > (by "using namespace std"), which confused doxygen.
> 
> Thanks for the clarification. I may see if Doxygen has a way to exclude 
> these warnings.

If we can suppress the warning at doxygen level that would be good
(but that would cause a side effect of false negatives).

Another approach is to introduce a coding guideline that declarations
and definitions should be consistent about name spaces even if other
part of the definition file allows omitting name spaces when possible.

Basically, the rule I've been personally using is

1. okay to use 'using namespace XXX;' in .cc (or even prefer it)
2. when possible omit unnecessary namespace prefixes in .cc
  (i.e. prefer std::sting to string).  this is because it will make
  statements shorter and help improve overall readability very much
3. in some rare cases where ambiguity can happen specify namespaces
  explicitly.

Unfortunately, d to the exception (#3) the style policy isn't 100%
consistent.  But I personally think it's okay since it's relatively
rare and IMO the improved readability thank to shorter statements
justifies the rare inconsistency.

The additional style guideline for doxygen introduces another style
inconsistency.  But I think we can live with it as long as it's
clearly documented.

---
JINMEI, Tatuya