[Doxygen-develop] Bug? Namespace aliases

[Howard K. <hka...@ma...>]

Are there problems with namespace aliases?


I have 2 libraries.

One is equivalent to the Microsoft Platform SDK -- I just use it.
It has a header file (BCC.HPP)
	/**
	 * @namespace BigComputerCorporation
	 * The big namespace blah blah blah 
	 */
	namespace BigComputerCorporation
	{
	...
	}
	/** 
	 * @namespace BCC
	 * Alias for BigComputerCorporation
	 */
	namespace BCC = BigComputerCorporation;
with some files like
	/**
	 * ...doxygen documentation...
	 */
	void BCC::SomeClass::SomeMethod() { ... }
and it has doxygen generated docs.

In my library, I have a header (REMORA.HPP)
	#include <BCC.HPP>
	namespace BigComputerCorporation
	{
	/**
	 * @namespace Remora
	 * A small addition blah blah blah
	 */
	namespace Remora
	{
	/**
	 * Nifty extension blah blah blah
	 */
	class NiftyExtension
	{
		public: static void blah();
	};
	}
	}
and a source file (REMORA.CPP)
	#include <REMORA.HPP>
	/**
	 * My docs that doxygen doesn't include in its output!
	 */
	void BCC::Remora::NiftyExtension::blah() { do_something_cool(); }


When I run Doxygen I see it preprocesses REMORA.HPP and REMORA.CPP, but the
generated docs only have the raw signatures -- blah()'s documentation is
*not* included in the output.

Doxygen also spews a warning message for blah() (and anything else specified
with the BCC namespace alias).


If I add to REMORA.HPP the snippet
	#if defined(DOXYGEN_SHOULD_SKIP_THIS)
	namespace BCC = BigComputerCorporation;
	#endif
then suddenly doxygen generates output with all my doccomments for blah()
and the like.


Why?

The "BCC" namespace alias statements seems to be handled properly if it's in
a file specified in the INPUT/FILE_PATTERNS tag, but if it's just #include'd
by one of the INPUT files then doxygen seems to ignore it (causing
downstream havoc).


Smells like a bug to me.

I've added the hackaround for now, but it seems pretty ugly -- especially as
we plan to break up some monolithic applications into collections of smaller
toolkits/SDKs, and we have some namespace aliases (everything's scoped to a
COMPANY::PROJECT namespace, and we use namespace aliases wherever we can as
the COMPANY and PROJECT names can be annoyingly long; namespace aliases to
the rescue! But doxygen doesn't seem to play nice with the other
children...).

	- Howard