doxygen-users

[Doxygen-users] EXPAND_AS_DEFINED and Poor Mans Inheritance

[Peter S. <pet...@hu...>]

Hello all

I one project, I'm forced to use C. I try to get some struct reuse and
sort of object inheritance with the following contruct:

//------ begin of example

#define BASECLASS \
    int         aMember;        /**< Members Doc */ \
    /* END OF BASECLASS */

/**
 * This is the base class
 */
typedef struct BaseClass {
    BASECLASS
} BaseClass;

/**
 * This is a derived class
 */
typedef struct DerivedClass {
    BASECLASS
    int         additionalMember;   /**< also documented */
} DerivedClass;

//------ end of example

To get the documentation right, I'm using the MACRO_EXPANSION,
EXPAND_ONLY_PREDEF and EXPAND_AS_DEFINED = BASECLASS macros. But that
works only halfway: the 'aMember' appears in the documentation if
HIDE_UNDOC_MEMBERS is not set, but without documentation.

It seems that the doxygen comments inside my macro BASECLASS are
swallowed during the preprocessing stage. I'd like to happen the macro
expansion first and then the extraction of the comments...

Is there a way to make this work?

Regards, Peter
-- 
    _   _        Peter Steiner <pet...@hu...>
  / /_/ /        Hug-Witschi AG <http://www.hugwi.ch/>
 /  _  /         Electronic Engineering
/_/ /_/  _   _   Industriestrasse 12
   / / / / / /   CH-3178 Boesingen
  / /_/ /_/ /    Tel  +41 31 740 44 44
 /_ _ _ _ _/     Fax  +41 31 740 44 45

Re: [Doxygen-users] EXPAND_AS_DEFINED and Poor Mans Inheritance

[Peter S. <pet...@hu...>]

Hello!

replying to myself...

On Mon, 14 May 2001 09:46:13 +0200, Peter Steiner wrote:

> I one project, I'm forced to use C. I try to get some struct reuse and
> sort of object inheritance with the following contruct:

> #define BASECLASS \
>     int         aMember;        /**< Members Doc */ \
>     /* END OF BASECLASS */

> /**
>  * This is the base class
>  */
> typedef struct BaseClass {
>     BASECLASS
> } BaseClass;

> To get the documentation right, I'm using the MACRO_EXPANSION,
> EXPAND_ONLY_PREDEF and EXPAND_AS_DEFINED = BASECLASS macros. But that
> works only halfway: the 'aMember' appears in the documentation if
> HIDE_UNDOC_MEMBERS is not set, but without documentation.

Looking at the output of "doxygen -d Preprocessor", the comments stay
where the macro definition was, they are not included into the body of a
macro. Now I did not look into the lex files to provide a patch (i don't
know lex/flex yet), but found a workaround using macros that also
illustrates the problem:

  #define DXY_PASTE(x,y) x ## y
  #define DXY(x)         DXY_PASTE(/,**<) x DXY_PASTE(*,/)

  #define BASECLASS \
      int         aMember;        DXY(Members Doc) \
      /* END OF BASECLASS */

  /// This is the base class
  typedef struct BaseClass {
      BASECLASS
  } BaseClass;

Using the DXY macro to get the comments past the lexical analysis seems
to work, but I don't know yet how portable this is for compilers.

It would be nice, if doxygen could handle this itself.

Regards, Peter
-- 
    _   _        Peter Steiner <pet...@hu...>
  / /_/ /        Hug-Witschi AG <http://www.hugwi.ch/>
 /  _  /         Electronic Engineering
/_/ /_/  _   _   Industriestrasse 12
   / / / / / /   CH-3178 Boesingen
  / /_/ /_/ /    Tel  +41 31 740 44 44
 /_ _ _ _ _/     Fax  +41 31 740 44 45

Re: [Doxygen-users] EXPAND_AS_DEFINED and Poor Mans Inheritance

[Hendrik S. <Do...@HS...>]

"Peter Steiner" <pet...@hu...> wrote:

> [...]
> It seems that the doxygen comments inside my macro BASECLASS are
> swallowed during the preprocessing stage. 

  AFAIK that's what the C++ standard says how it should be. 
  If your compiler('s preprocessor) behaves differently 
  then that's either a bug or feature of it. ;^> 

[...]
> Regards, Peter

  Schobi

[...]

Re: [Doxygen-users] EXPAND_AS_DEFINED and Poor Mans Inheritance

[Peter S. <pet...@hu...>]

On Sun, 10 Jun 2001 23:02:34 +0200, Hendrik Schober wrote:

> "Peter Steiner" <pet...@hu...> wrote:

>> [...]
>> It seems that the doxygen comments inside my macro BASECLASS are
>> swallowed during the preprocessing stage. 

>   AFAIK that's what the C++ standard says how it should be. 

Where does it state this? A very quick glance at section 2.7 (Comments)
and chapter 16 (Preprocessing Directives) didn't give any statement
_when_ to remove comments. To be exactly, I'm more interested in the C
standard in this case anyway, as the source is C (or I'd be able to use
C++ inheritance instead of some obscure macro technology...)

And as doxygen does not see the fully preprocessed source
(or it wouldn't see _any_ comment), it doesn't really matter what the
C++ or C standard says...

>   If your compiler('s preprocessor) behaves differently 
>   then that's either a bug or feature of it. ;^> 

My compiler's preprocessor does what it should: it removes this
comments. But doxygen doesn't use the compilers preprocessor, it uses
its own. I just plea for this _feature_ inside doxygen...

Regards

Peter
-- 
    _   _        Peter Steiner <pet...@hu...>
  / /_/ /        Hug-Witschi AG <http://www.hugwi.ch/>
 /  _  /         Electronic Engineering
/_/ /_/  _   _   Industriestrasse 12
   / / / / / /   CH-3178 Boesingen
  / /_/ /_/ /    Tel  +41 31 740 44 44
 /_ _ _ _ _/     Fax  +41 31 740 44 45

Re: [Doxygen-users] EXPAND_AS_DEFINED and Poor Mans Inheritance

[Hendrik S. <Do...@HS...>]

"Peter Steiner" <pet...@hu...> wrote:

> On Sun, 10 Jun 2001 23:02:34 +0200, Hendrik Schober wrote:
> 
> > "Peter Steiner" <pet...@hu...> wrote:
> 
> >> [...]
> >> It seems that the doxygen comments inside my macro BASECLASS are
> >> swallowed during the preprocessing stage. 
> 
> >   AFAIK that's what the C++ standard says how it should be. 
> 
> Where does it state this? A very quick glance at section 2.7 (Comments)
> and chapter 16 (Preprocessing Directives) didn't give any statement
> _when_ to remove comments. 

  Sorry, no chapter and verse available from me. 
  My English is way to bad to read the C++ standard 
  (except when I have a hard time to fall asleep).
  It's what I seem to remember from discussions on 
  comp.lang-c++.moderated. 

>                            To be exactly, I'm more interested in the C
> standard in this case anyway, as the source is C (or I'd be able to use
> C++ inheritance instead of some obscure macro technology...)

  Oh, C. No idea. 

> And as doxygen does not see the fully preprocessed source
> (or it wouldn't see _any_ comment), it doesn't really matter what the
> C++ or C standard says...

  What I meant was, that doxygen seems to be C++ 
  standard compliant in respect to comments within 
  preprocessor macros. 

> [...] But doxygen doesn't use the compilers preprocessor, it uses
> its own. I just plea for this _feature_ inside doxygen...

  Ah, I see. I guess it was too late last night... 

> Regards
> 
> Peter

  Schobi