[Doxygen-users] Documenting #included files

[Trevor R. <Tre...@pe...>]

Hello,

Could anyone (Dimitri?) tell me if it is possible to get Doxygen to document
the contents of a file that is #included inside another file?

Specifically, I need to include a header multiple times, but with different
#defined placeholders.  Basically, I'm trying to emulate a class template
with a macro "hack" (as in the pre-template days).  I know it's evil, but
I'm writing a portability library, and many of our tools are deficient in
handling templates.  For example, Visual C++ 6 has so many caveats (some
documented, some not) on exporting template instantiations through a DLL
that it's effectively incapable of it.  Also, the Visual Studio debugger
apparently doesn't understand polymorphic templates.  (It will show you the
derived class of an object through a base class pointer for a normal class,
but not for template classes.)

Anyway, here's an example.  I want to see both CPSAbstractByteBuffer and
CPSAbstractCharBuffer documented, but not PS_ABSTRACT_T_BUFFER.

psabstractbuffer.h:

/**
 * Abstract dynamic buffer class.
 */
class PSCL_IMPEXP PS_ABSTRACT_T_BUFFER : public CPSObject
{
public:
    virtual const T* GetData() const = 0;
...
};

psbuffer.h:

#define T                               PS_BYTE
#define PS_ABSTRACT_T_BUFFER            CPSAbstractByteBuffer
#include "psabstractbuffer.h"
#undef T
#undef PS_ABSTRACT_T_BUFFER

#define T                               PS_CHAR
#define PS_ABSTRACT_T_BUFFER            CPSAbstractCharBuffer
#include "psabstractbuffer.h"
#undef T
#undef PS_ABSTRACT_T_BUFFER

If Doxygen doesn't do this now, does anyone agree that it would be nice to
have some way of doing this?  Maybe a \docinclude special command?  Not
because you want to emulate class templates necessarily, but because you
might like to make it appear that a header contains definitions that it
incidentally #includes from other files.  The end user only cares about what
header he should include to get those definitions, and should be insulated
from how the designer chooses to divide up his files.  Of course, the way
Doxygen works now is the best default.

Thanks,
Trevor