Thread: [Doxygen-users] documenting multiple methods defined by a single macro - help
Brought to you by:
dimitri
Menu
▾
▴
doxygen-users
|
From: Manfred D. <man...@me...> - 2005-11-29 08:39:51
|
Hi:
Can anyone let me know how I would even begin to document the following
macros?
Note: the macro below encapsulates 2 methods, which in fact result in
22 (yes 22, not 20) declarations in all (it's an iterative macro).
#define RESHAPE_DIM_MAX 10
#define RESHAPE(z, N, _) \
\
static void reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz, \
MoeArray<T>& data \
) \
throw(); \
\
static boost::shared_ptr<MoeArray<T> > \
reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz) throw(); \
/**/
BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _)
#undef RESHAPE
Thanks in advance,
--
Manfred Doudar
MetOcean Engineers
www.metoceanengineers.com
|
|
From: <mx...@se...> - 2005-11-29 10:34:51
|
The MACROS you can document very easy, e.g.
/**
* The macro documentation.
*/
#define RESHAPE(z, N, _)
...
or
/**
* @def RESHAPE
*
* The macro documentation.
*/
...
However, if you want to document the methods inside the RESHAPE macro,
did you try following?:
#define RESHAPE(z, N, _) \
\
/** \
* reshape method documentation. \
*/ \
static void reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz, \
MoeArray<T>& data \
) \
throw(); \
\
/** \
* reshape2 method documentation. \
*/ \
static boost::shared_ptr<MoeArray<T> > \
reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz) throw(); \
/**/
Of course, you have to use precompiler to expand this macro, setting at
least:
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
SEARCH_INCLUDES = YES
INCLUDE_PATH = <path to your includes which contains expanded
macros>
[INCLUDE_FILE_PATTERNS = <...>]
and
EXPAND_AS_DEFINED = RESHAPE
or
EXPAND_ONLY_PREDEF = NO
will expand all macros, not only predefined (but it can be potentialy
problematic)
* hint: run "doxygen -d Preprocessor <your_config.dox> >PreProcess.txt"
to see the result of macro expansion.
Manfred Doudar wrote:
>
> Hi:
>
> Can anyone let me know how I would even begin to document the following
> macros?
>
> Note: the macro below encapsulates 2 methods, which in fact result in
> 22 (yes 22, not 20) declarations in all (it's an iterative macro).
>
>
>
>
> #define RESHAPE_DIM_MAX 10
>
>
> #define RESHAPE(z, N, _) \
> \
> static void reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz, \
> MoeArray<T>& data \
> ) \
> throw(); \
> \
> static boost::shared_ptr<MoeArray<T> > \
> reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz) throw(); \
> /**/
>
>
> BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _)
>
> #undef RESHAPE
>
>
>
> Thanks in advance,
|
|
From: Manfred D. <man...@me...> - 2005-11-29 11:34:00
|
mx...@se... wrote: > > The MACROS you can document very easy, e.g. > > /** > * The macro documentation. > */ > #define RESHAPE(z, N, _) > ... > > or > > /** > * @def RESHAPE > * > * The macro documentation. > */ > ... > > However, if you want to document the methods inside the RESHAPE macro, > did you try following?: > > #define RESHAPE(z, N, _) \ > \ > /** \ > * reshape method documentation. \ > */ \ > static void reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz, \ > MoeArray<T>& data \ > ) \ > throw(); \ > \ > /** \ > * reshape2 method documentation. \ > */ \ > static boost::shared_ptr<MoeArray<T> > \ > reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz) throw(); \ > /**/ > > > Of course, you have to use precompiler to expand this macro, setting at > least: > > ENABLE_PREPROCESSING = YES > MACRO_EXPANSION = YES > EXPAND_ONLY_PREDEF = YES > SEARCH_INCLUDES = YES > INCLUDE_PATH = <path to your includes which contains expanded > macros> > [INCLUDE_FILE_PATTERNS = <...>] > > and > > EXPAND_AS_DEFINED = RESHAPE > > or > EXPAND_ONLY_PREDEF = NO > will expand all macros, not only predefined (but it can be potentialy > problematic) > > * hint: run "doxygen -d Preprocessor <your_config.dox> >PreProcess.txt" > to see the result of macro expansion. > > Yes - that's what I'm trying to do... but still no success :-( Running with the -d option (doxygen -d Preprocessor <config.dox>), yielded the following suprise: 00094 /** 00095 * 00096 * @def RESHAPE 00097 * 00098 * The macro documentaion is here. 00099 */ 00100 #define RESHAPE(z, N, _) 00101 00102 00103 00104 00105 00106 00107 00108 00109 00110 00111 /**/ 00112 00113 00114 BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _) 00115 ... As you can see, there's nothing there - this one has really got me. -Any other ideas ?? Cheers, -- Manfred MetOcean Engineers www.metoceanengineers.com > > > Manfred Doudar wrote: > >> >> Hi: >> >> Can anyone let me know how I would even begin to document the >> following macros? >> >> Note: the macro below encapsulates 2 methods, which in fact result in >> 22 (yes 22, not 20) declarations in all (it's an iterative macro). >> >> >> >> >> #define RESHAPE_DIM_MAX 10 >> >> >> #define RESHAPE(z, N, _) \ >> \ >> static void reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz, \ >> MoeArray<T>& data \ >> ) \ >> throw(); \ >> \ >> static boost::shared_ptr<MoeArray<T> > \ >> reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz) throw(); \ >> /**/ >> >> >> BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _) >> >> #undef RESHAPE >> >> >> >> Thanks in advance, > |
|
From: Manfred D. <man...@me...> - 2005-11-29 11:57:27
|
Manfred Doudar wrote: > mx...@se... wrote: > >> >> The MACROS you can document very easy, e.g. >> [snip] >> ... >> >> However, if you want to document the methods inside the RESHAPE macro, >> did you try following?: >> [snip] >> Of course, you have to use precompiler to expand this macro, setting >> at least: >> >> ENABLE_PREPROCESSING = YES >> MACRO_EXPANSION = YES >> EXPAND_ONLY_PREDEF = YES >> SEARCH_INCLUDES = YES >> INCLUDE_PATH = <path to your includes which contains >> expanded macros> Oops! ... do you mean to tell me that I need to provide a file for doxygen with the expanded macro definition (, so in my case, all 22 macro expansions) ? ...Please, please tell me that's not the case :-( >> > > Yes - that's what I'm trying to do... but still no success :-( > > Running with the -d option (doxygen -d Preprocessor <config.dox>), > yielded the following suprise: > > |
|
From: <mx...@se...> - 2005-11-29 12:13:22
|
Manfred Doudar wrote: > > Oops! ... do you mean to tell me that I need to provide a file for > doxygen with the expanded macro definition (, so in my case, all 22 > macro expansions) ? > > ...Please, please tell me that's not the case :-( > No, you only need to include the header where the macro itself is defined (and it should IMHO work if you expand it in the same file e.g. header where you have defined it as it seems in your case). |
|
From: <mx...@se...> - 2005-11-29 12:10:17
|
You get evidently the macro not expanded, which means you have bad setup in some way. * maybe you want to expand even the macros BOOST_PP_REPEAT BOOST_PP_INC RESHAPE_DIM_MAX etc. (EXPAND_AS_DEFINED = RESHAPE BOOST_PP_REPEAT BOOST_PP_INC RESHAPE_DIM_MAX) or in first try you can set EXPAND_ONLY_PREDEF = NO and see what happens. * in the BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _) there are missing RESHAPE macro parameters? And you must have included the headers where the macro is defined in every file you want to expand the macro (=every .h and directly or indirectly every .cpp), and the path to the macro header (and another headers if you include the header indirectly) must be set in INCLUDE_PATH = ... (it does NOT suffice to have this file only in INPUT files). Manfred Doudar wrote: > > Yes - that's what I'm trying to do... but still no success :-( > > Running with the -d option (doxygen -d Preprocessor <config.dox>), > yielded the following suprise: > > > 00094 /** > 00095 * > 00096 * @def RESHAPE > 00097 * > 00098 * The macro documentaion is here. > 00099 */ > 00100 #define RESHAPE(z, N, _) > 00101 > 00102 > 00103 > 00104 > 00105 > 00106 > 00107 > 00108 > 00109 > 00110 > 00111 /**/ > 00112 > 00113 > 00114 BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _) > 00115 > > > > ... As you can see, there's nothing there - this one has really got me. > > -Any other ideas ?? > > |
|
From: Manfred D. <man...@me...> - 2005-11-30 03:00:12
|
mx...@se... wrote:
>
> You get evidently the macro not expanded, which means you have bad setup
> in some way.
>
> * maybe you want to expand even the macros BOOST_PP_REPEAT BOOST_PP_INC
> RESHAPE_DIM_MAX etc.
> (EXPAND_AS_DEFINED = RESHAPE BOOST_PP_REPEAT BOOST_PP_INC
> RESHAPE_DIM_MAX)
that seems like a reasonable proposition at first, but wouldn't that
mean having to `@def` the macros BOOST_PP_REPEAT and BOOST_PP_INC in the
files they are defined?
-if that's the case, then it's problematic ... because the PP_REPEAT,
PP_INC are third party [C++ Boost library] macros, and it certainly
would be a bad idea to doxygenize the Boost library sources; that'd be a
maintenance nightmare at the very least (especially considering periodic
updates to the Boost libs).
>
> or in first try you can set EXPAND_ONLY_PREDEF = NO and see what
> happens.
no luck here :-(
>
> * in the BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _)
> there are missing RESHAPE macro parameters?
>
no, it's rightly coded. You can quickly make doubly sure by trying the
following:
g++ -P -E <source-file>
(... must have the C++ Boost libraries installed though)
>
> And you must have included the headers where the macro is defined in
> every file you want to expand the macro (=every .h and directly or
> indirectly every .cpp), and the path to the macro header (and another
> headers if you include the header indirectly) must be set in
> INCLUDE_PATH = ... (it does NOT suffice to have this file only in INPUT
> files).
>
>
Yes, that's been done for sure.
I'll have to keep trying I guess, ... and it's going to take a lot of
head scratching to acheive, if it is at all possible.
Cheers,
--
Manfred Doudar
MetOcean Engineers
www.metoceanengineers.com
|
|
From: <mx...@se...> - 2005-11-30 08:17:37
|
Manfred Doudar wrote: > mx...@se... wrote: > >> >> You get evidently the macro not expanded, which means you have bad >> setup in some way. >> >> * maybe you want to expand even the macros BOOST_PP_REPEAT >> BOOST_PP_INC RESHAPE_DIM_MAX etc. >> (EXPAND_AS_DEFINED = RESHAPE BOOST_PP_REPEAT BOOST_PP_INC >> RESHAPE_DIM_MAX) > > > > that seems like a reasonable proposition at first, but wouldn't that > mean having to `@def` the macros BOOST_PP_REPEAT and BOOST_PP_INC in the > files they are defined? > > -if that's the case, then it's problematic ... because the PP_REPEAT, > PP_INC are third party [C++ Boost library] macros, and it certainly > would be a bad idea to doxygenize the Boost library sources; that'd be a > maintenance nightmare at the very least (especially considering periodic > updates to the Boost libs). > The point is, that if you include the Boost library headers (where the macros BOOST_PP_REPEAT and BOOST_PP_INC are defined, you *really* need it to get the macro expansion work) in "INCLUDE_PATH", that is only for macro search and expansion purposes (better said for preprocessor purposes), and these sources *will not be doxygenized* (if you not include these paths in "INPUT" locations too, of course). (the Doxygen documentation says following about the INCLUDE_PATH: # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by # the preprocessor.) * hint: if you have some environment variable defined to point to Boost library location, you can use this environment variable as e.g. INCLUDE_PATH = $(WXWIN)/include/wx (this works fine for me) |
|
From: Manfred D. <man...@me...> - 2005-11-30 09:01:38
|
mx...@se... wrote: > > > Manfred Doudar wrote: > >> mx...@se... wrote: >> >>> [snip] > > The point is, that if you include the Boost library headers (where the > macros BOOST_PP_REPEAT and BOOST_PP_INC are defined, you *really* need > it to get the macro expansion work) in "INCLUDE_PATH", that is only for > macro search and expansion purposes (better said for preprocessor > purposes), and these sources *will not be doxygenized* (if you not > include these paths in "INPUT" locations too, of course). > > (the Doxygen documentation says following about the INCLUDE_PATH: > # The INCLUDE_PATH tag can be used to specify one or more directories that > # contain include files that are not input files but should be processed by > # the preprocessor.) > > > * hint: if you have some environment variable defined to point to Boost > library location, you can use this environment variable as e.g. > INCLUDE_PATH = $(WXWIN)/include/wx > (this works fine for me) > > Ok, now I am with you ... thankyou so much for your forebearance, (I'm feeling rather stupid right now, this should have occured to me much earlier). MX0 - you've been most helpful, thanks so very much. Cheers, -- Manfred Doudar MetOcean Engineers www.metoceanengineers.com |
|
From: Sven B. <sv...@as...> - 2005-11-29 12:49:38
|
Holy shit, I think when you spend time to document these sources, you could also spend some time to throw away these old code fragments. As I see, you use the boost library, so your compiler should be able to handle it and the STL. On Tuesday 29 November 2005 09:40, Manfred Doudar wrote: > #define RESHAPE_DIM_MAX 10 > this kind of constant definition is obsolete. > #define RESHAPE(z, N, _) \ > \ > static void reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz, \ > MoeArray<T>& data \ > ) \ > throw(); \ > \ > static boost::shared_ptr<MoeArray<T> > \ > reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz) throw(); \ > /**/ > > > BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _) > > #undef RESHAPE > this is also obsolete. use typedef instead. Greetz, Sven |
|
From: Manfred D. <man...@me...> - 2005-11-30 01:57:49
|
Sven Bauhan wrote:
> As I see, you use the boost library, so your compiler should be able to handle
> it and the STL.
>
That's right - and indeed the compiler does handle the Boost code, and
the STL.
> On Tuesday 29 November 2005 09:40, Manfred Doudar wrote:
>
>>#define RESHAPE_DIM_MAX 10
>>
>
> this kind of constant definition is obsolete.
No, it's not. -It defines in one place in the header, the level of
macro recursion, upto one less than the array rank I want to support.
Should one day we want to alter this, we only need modify the value held
at RESHAPE_DIM_MAX
>
>
>>#define RESHAPE(z, N, _) \
>> \
>> static void reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz, \
>> MoeArray<T>& data \
>> ) \
>> throw(); \
>> \
>> static boost::shared_ptr<MoeArray<T> > \
>> reshape(const blitz::Array<T, BOOST_PP_INC(N)>& btz) throw(); \
>> /**/
>>
>>
>> BOOST_PP_REPEAT(BOOST_PP_INC(RESHAPE_DIM_MAX), RESHAPE, _)
>>
>>#undef RESHAPE
>>
>
> this is also obsolete. use typedef instead.
Not quite. These are declarations, and the definitions are similarly
written. -The Boost PP library is an ideal candidate for this kind of code.
The point of the above code is to cut down on boiler-plate code, so I
can reduce maintenence of the code, and cut down on transcription
errors, and copy/paste ... - that is I don't want to be writing the
following explicitly in code:
static void reshape(const blitz::Array<T, 1>& btz,
MoeArray<T>& data
)
throw();
static void reshape(const blitz::Array<T, 2>& btz,
MoeArray<T>& data
)
throw();
static void reshape(const blitz::Array<T, 3>& btz,
MoeArray<T>& data
)
throw();
...
static void reshape(const blitz::Array<T, 11>& btz,
MoeArray<T>& data
)
throw();
... and ...
static boost::shared_ptr<MoeArray<T> >
reshape(const blitz::Array<T, 1>& btz) throw();
static boost::shared_ptr<MoeArray<T> >
reshape(const blitz::Array<T, 2>& btz) throw();
static boost::shared_ptr<MoeArray<T> >
reshape(const blitz::Array<T, 3>& btz) throw();
...
static boost::shared_ptr<MoeArray<T> >
reshape(const blitz::Array<T, 11>& btz) throw();
... and then imagine the amount of repition and boiler-plate code you'll
have to duplicate in the definitions, not to mention maintence of such
code, and how error prone and messy it would be.
With the macros, the code is as close to readable as you're going to
get; and sure you *could* typedef the boost::shared_ptr<MoeArray<T> >
but you're not going to win much.
Cheers,
--
Manfred Doudar
MetOcean Engineers
www.metoceanengineers.com
|
|
From: Johann G. <jo...@ge...> - 2005-11-30 07:21:19
|
> > (Sven Bauhan) this kind of constant definition is obsolete. > (Manfred Doudar) No, it's not. I guess he meant "Don't use #define when there exists typesafe alternatives". I agree with him 100%, but its not a discussion for this list. > > this is also obsolete. use typedef instead. > Not quite. I guess he meant "Don't use #define when there exists typesafe, and more flexible and debuggable alternatives, such as inline functions". I agree with him 100%, but its not a discussion for this list. -- Johann Gerell Software Design Engineer Phone: +46 (0) 8 678 18 50 Fax: +46 (0) 8 678 18 51 N1: +46 (0) 733 89 49 78 E-mail: joh...@ne... Web: www.neonode.com Neonode AB Biblioteksgatan 11, 1:st floor. SE-111 46 Stockholm, SWEDEN |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X