help with macros
Burlen Loring <[email protected]> Thu, 29 Apr 2021 08:30:45 -0700
| Newsgroups | gmane.text.doxygen.general |
|---|---|
| Message-ID | <[email protected]> |
This is a multi-part message in MIME format.
--===============1891254447710744510==
Content-Type: multipart/alternative;
boundary="------------B249CD83E1FF54CAB1CFDC81"
Content-Language: en-US
This is a multi-part message in MIME format.
--------------B249CD83E1FF54CAB1CFDC81
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
We are integrating Doxygen into a large existing C++ project. The
project make extensive use of macros in certain inheritance hierarchies
where consistency of interface and implementation are required. This
seems to be causing Doxygen some trouble. The problem I'm having is that
no related errors or warnings are emitted. I'm stuck, and not sure how
to get some actionable info about what the problem and solution might be.
Here's an example of such a macro
#define TECA_ALGORITHM_PROPERTY(T, NAME) \
\
/** Set the value of the NAME algorithm property */ \
void set_##NAME(const T &v) \
{ \
if (this->NAME != v) \
{ \
this->NAME = v; \
this->set_modified(); \
} \
} \
\
/** Get the value of the NAME algorithm property */ \
const T &get_##NAME() const \
{ \
return this->NAME; \
}
For context, a link to its definition in the code base (a number of
similar macros are defined there as well)
https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/core/teca_algorithm.h#L84
Where this macro is used in a class we want to Doxygen the use, by
having a group like this:
/** @name files_regex
* Set a regular expression identifying the set of files
comprising the
* dataset. This should contain the full path to the files and
the regular
* expression. Only the final component of a path may contain
a regex.
* Be aware that regular expression control characters do not
have the
* same meaning as shell glob control characters. When used in
a shell
* regular expression control characters need to be quoted or
escaped to
* prevent the shell from interpreting them.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, files_regex)
///@}
For context here is the use in class definition:
https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/io/teca_cf_reader.h#L99
The resulting Doxygen web pages however do not include any of the class
methods, only the brief and detailed class description.
https://teca.readthedocs.io/en/integrating_breathe/doxygen/classteca__cf__reader.html
no warning or error are emitted.
I've tried various Doxyfile settings, here is what I'm using
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
SKIP_FUNCTION_MACROS = YES
I experimented with
SKIP_FUNCTION_MACROS = NO
However, with SKIP_FUNCTION_MACROS = NO any class that used the macros
was dropped from the site entirely. There were many warnings issued on
the class constructors about the macro not ending in a semi colon. I
don't understand why macros would end in a semi colon as that's not a
language requirement and makes no sense for defining functions like the
macros in question here do - the appropriate terminating character is }
not ;. Not sure how to work around that.
My questions are: Should Doxygen be able to handle this? Does anyone
know what the issue might be? If not how could we get some actionable
info about the failures?
Thank you!
--------------B249CD83E1FF54CAB1CFDC81
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body>
We are integrating Doxygen into a large existing C++ project. The
project make extensive use of macros in certain inheritance
hierarchies where consistency of interface and implementation are
required. This seems to be causing Doxygen some trouble. The problem
I'm having is that no related errors or warnings are emitted. I'm
stuck, and not sure how to get some actionable info about what the
problem and solution might be.<br>
<br>
Here's an example of such a macro<br>
<br>
<blockquote><font face="monospace">#define
TECA_ALGORITHM_PROPERTY(T, NAME) \</font><br>
<font face="monospace">
\</font><br>
<font face="monospace">/** Set the value of the NAME algorithm
property */ \</font><br>
<font face="monospace">void set_##NAME(const T
&v) \</font><br>
<font face="monospace">{
\</font><br>
<font face="monospace"> if (this->NAME !=
v) \</font><br>
<font face="monospace">
{ \</font><br>
<font face="monospace"> this->NAME =
v; \</font><br>
<font face="monospace">
this->set_modified(); \</font><br>
<font face="monospace">
} \</font><br>
<font face="monospace">}
\</font><br>
<font face="monospace">
\</font><br>
<font face="monospace">/** Get the value of the NAME algorithm
property */ \</font><br>
<font face="monospace">const T &get_##NAME()
const \</font><br>
<font face="monospace">{
\</font><br>
<font face="monospace"> return
this->NAME; \</font><br>
<font face="monospace">}</font><br>
<br>
</blockquote>
For context, a link to its definition in the code base (a number of
similar macros are defined there as well)<br>
<a class="moz-txt-link-freetext" href="https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/core/teca_algorithm.h#L84">https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/core/teca_algorithm.h#L84</a><br>
<br>
Where this macro is used in a class we want to Doxygen the use, by
having a group like this:<br>
<br>
<blockquote><font face="monospace"> /** @name files_regex</font><br>
<font face="monospace"> * Set a regular expression identifying
the set of files comprising the</font><br>
<font face="monospace"> * dataset. This should contain the
full path to the files and the regular</font><br>
<font face="monospace"> * expression. Only the final
component of a path may contain a regex.</font><br>
<font face="monospace"> * Be aware that regular expression
control characters do not have the</font><br>
<font face="monospace"> * same meaning as shell glob control
characters. When used in a shell</font><br>
<font face="monospace"> * regular expression control
characters need to be quoted or escaped to</font><br>
<font face="monospace"> * prevent the shell from interpreting
them.</font><br>
<font face="monospace"> */</font><br>
<font face="monospace"> ///@{</font><br>
<font face="monospace"> TECA_ALGORITHM_PROPERTY(std::string,
files_regex)</font><br>
<font face="monospace"> ///@}</font><br>
</blockquote>
For context here is the use in class definition:<br>
<a class="moz-txt-link-freetext" href="https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/io/teca_cf_reader.h#L99">https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/io/teca_cf_reader.h#L99</a><br>
<br>
The resulting Doxygen web pages however do not include any of the
class methods, only the brief and detailed class description.<br>
<a class="moz-txt-link-freetext" href="https://teca.readthedocs.io/en/integrating_breathe/doxygen/classteca__cf__reader.html">https://teca.readthedocs.io/en/integrating_breathe/doxygen/classteca__cf__reader.html</a><br>
<br>
no warning or error are emitted.<br>
<br>
I've tried various Doxyfile settings, here is what I'm using<br>
<blockquote><font face="monospace">ENABLE_PREPROCESSING = YES</font><br>
<font face="monospace">MACRO_EXPANSION = YES<br>
EXPAND_ONLY_PREDEF = NO</font><br>
<font face="monospace"><font face="monospace">SKIP_FUNCTION_MACROS
= YES<br>
</font></font></blockquote>
I experimented with<br>
<blockquote><font face="monospace">SKIP_FUNCTION_MACROS = NO</font><br>
</blockquote>
However, with <font face="monospace">SKIP_FUNCTION_MACROS = NO </font>any
class that used the macros was dropped from the site entirely. There
were many warnings issued on the class constructors about the macro
not ending in a semi colon. I don't understand why macros would end
in a semi colon as that's not a language requirement and makes no
sense for defining functions like the macros in question here do -
the appropriate terminating character is } not ;. Not sure how to
work around that.<br>
<br>
My questions are: Should Doxygen be able to handle this? Does anyone
know what the issue might be? If not how could we get some
actionable info about the failures?<br>
<br>
Thank you!<br>
<br>
<br>
</body>
</html>
--------------B249CD83E1FF54CAB1CFDC81--
--===============1891254447710744510==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
--===============1891254447710744510==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
_______________________________________________
Doxygen-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
--===============1891254447710744510==--