doxygen-users

[Doxygen-users] Getting macro expansion to work

[Simon W. <sim...@ma...>]

I just cant seem to get a C++ #define'd macro to be expanded before
documentation.  I have set:

	MACRO_EXPANSION = YES
	EXPAND_ONLY_PREDEF = YES
	EXPAND_AS_DEFINED = ((macros))

The macros I need to expand expand to inline accessor methods in a
class, each macro giving two or three methods.

I have already set up the build to put all my header files into the
INPUTS config param (massaging g++ -MM output).

The manual section on Preprocessing give examples of the use of
PREDEFINED, but not EXPAND_AS_DEFINED.  

My macros have the form:

#define ACCESS_STRING(NAME,FIELD,LENGTH) \
	string get_ ## NAME () {\
		return string (data.FIELD, LENGTH);\
	}\
	---><8--- similar for set_

#define ITERATOR(NAME,TYPE,INFO) \
	TYPE::iterator begin_ ## NAME () {\
		return begin_tmpl < TYPE > (INFO);\
	}\
	---><8--- similar for end_ and add_

So my EXPAND_AS_DEFINED field is

	EXPAND_AS_DEFINED = "ACCESS_STRING(NAME,FIELD,LENGTH)" \
	                    "ITERATOR(NAME,TYPE,INFO)"

I have checked the C++ pre-processor output, and these are correctly
defined in the resultant .ii file.

In the Doxygen (1.2.1) output, The "ACCESS_STRING" macro appears once or
not at all in the doc (HTML).  Where it appears, it is as a method
without return, eg:

	Patient::ACCESS_STRING (name, p_name, 17)


While the "ITERATOR" macro doesnt appear in the class docs at all.  Both
are documented as macros though.

So, what is confusing Doxygen (pre-processor) here?  



Si.



-- 
Simon A Watts
Software Engineer
Marconi Medical Systems
mailto:sim...@ma...
tel: +44(0) 1252 747 311

[Doxygen-users] Re: Getting macro expansion to work

[Simon W. <sim...@ma...>]

...and I should mention that I have ENABLE_PREPROCESSING=YES, and am
including undocumented functions/methods in the output.


Si.


-- 
Simon A Watts
Software Engineer
Marconi Medical Systems
mailto:sim...@ma...
tel: +44(0) 1252 747 311

Re: [Doxygen-users] Getting macro expansion to work

[Dimitri v. H. <di...@st...>]

On Thu, Oct 11, 2001 at 10:46:09AM +0000, Simon Watts wrote:
> I just cant seem to get a C++ #define'd macro to be expanded before
> documentation.  I have set:
> 
> 	MACRO_EXPANSION = YES
> 	EXPAND_ONLY_PREDEF = YES
> 	EXPAND_AS_DEFINED = ((macros))
> 
> So my EXPAND_AS_DEFINED field is
> 
> 	EXPAND_AS_DEFINED = "ACCESS_STRING(NAME,FIELD,LENGTH)" \
> 	                    "ITERATOR(NAME,TYPE,INFO)"

Please try

EXPAND_AS_DEFINED = ACCESS_STRING ITERATOR

So just macro names without the arguments. This should work.

Regards,
  Dimitri

[Doxygen-users] Re: Getting macro expansion to work

[Simon W. <sim...@ma...>]

FROM: Dimitri van Heesch
DATE: 10/14/2001 11:14:02
> On Thu, Oct 11, 2001 at 10:46:09AM +0000, Simon Watts wrote:
> > I just cant seem to get a C++ #define'd macro to be expanded before
> > documentation.  I have set:
> > > MACRO_EXPANSION = YES
> > EXPAND_ONLY_PREDEF = YES
> > EXPAND_AS_DEFINED = ((macros))
> > > So my EXPAND_AS_DEFINED field is
> > > EXPAND_AS_DEFINED = "ACCESS_STRING(NAME,FIELD,LENGTH)" \
> > "ITERATOR(NAME,TYPE,INFO)"
> Please try
> EXPAND_AS_DEFINED = ACCESS_STRING ITERATOR
> So just macro names without the arguments. This should work.


I have tried this, but I still get the Macros appearing as-if methods in
the classes.

I am driving doxygen from a make file, which builds the config as a
variable string echoed to doxygen on stdin.  Other parameters in the
config appear to be working.  I need to do it this way, rather than
having a dedicated config file, because I am building a framework in
make which will be used on several modules by different people, and I
want to limit others need to know the internals.

The make variable is build up incrementally, thus:

DOXYFILE += EXPAND_AS_DEFINED\=ACCESS_STRING ITERATOR\\n

which produces the right effects with

  echo -ne $(DOXYFILE) | $(DOXYGEN) -

Which echos as (editing for anonymity):

 @INCLUDE_PATH=/path/to/make/system
 @INCLUDE=default-doxyfile
 INCLUDE_PATH=/master/include /project/include
 PERL_PATH=/usr/bin/perl
 HAVE_DOT=YES
 DOT_PATH=/usr/bin
 PROJECT_NAME=My Project
 PROJECT_NUMBER=0.0.0
 EXPAND_AS_DEFINED=ACCESS_STRING ITERATOR
 INPUT= ...<snip>

Other stuff is defined in the "default-doxyfile" at
"/path/to/make/system".  I'll attach that file anyway -- its mainly the
default config with some options enabled (comments stripped for size).


The macros are used within class definition body in the various headers,
and expand to be inline methods of the class.  eg,

class Foo {
  ...
  ACCESS_STRING (name,m_name,17);
  ...
};

gives

class Foo {
  ...
  string get_name () { return string (data.m_name, 17); };
  ...
};

((
I know that the trailing comma after the function inline isnt C++, but
GCC 2.96 does not complain, and it seems to help Doxygen parse the
macros in the first place.  Without it, it gets confused and following
lines in the header vanish.  I actually define the macro as ending in 
"//" in case this hides the ";".
))



Si.


-- 
Simon A Watts
Software Engineer
Marconi Medical Systems
mailto:sim...@ma...
tel: +44(0) 1252 747 311