Documenting macro which are not defined in the code

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Documenting macro which are not defined in the code

eldiener
In my library there are is a macro which, if defined at all by the
end-user, changes the way the code works. I want to include this macro
in the doxygen documentation to my library. So I add the doxygen comments:

/** @file some_header.hpp
     @brief Some brief file description.

     Some longer file description.
*/

/** @def MYLIB_SOME_MACRO
     @brief When this macro is defined at all, changes the way that xxx
works.

     When this macro is defined at all xxx works in such and such way
     whereas when this macro is not defined xxx works in so and so way.
*/

Unfortunately because the macro itself is never actually defined in any
header, when I run doxygen I get output such as:

Somepath/some_header.hpp:7: warning: documentation for unknown define
MYLIB_SOME_MACRO found.

In other words even though I want to include the documentation for the
MYLIB_SOME_MACRO macro in my doxygen documentation it is rejected
because the macro is never actually defined in any of the source files
which doxygen parses.

is there any way to tell doxygen to include the doxygen comments for the
macro in its documentation even though the macro is not actually defined
anywhere ?













------------------------------------------------------------------------------
Find and fix application performance issues faster with Applications Manager
Applications Manager provides deep performance insights into multiple tiers of
your business applications. It resolves application problems quickly and
reduces your MTTR. Get your free trial!
https://ad.doubleclick.net/ddm/clk/302982198;130105516;z
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|

Re: Documenting macro which are not defined in the code

Richard Damon
On 4/26/16 3:37 AM, Edward Diener wrote:

> In my library there are is a macro which, if defined at all by the
> end-user, changes the way the code works. I want to include this macro
> in the doxygen documentation to my library. So I add the doxygen comments:
>
> /** @file some_header.hpp
>       @brief Some brief file description.
>
>       Some longer file description.
> */
>
> /** @def MYLIB_SOME_MACRO
>       @brief When this macro is defined at all, changes the way that xxx
> works.
>
>       When this macro is defined at all xxx works in such and such way
>       whereas when this macro is not defined xxx works in so and so way.
> */
>
> Unfortunately because the macro itself is never actually defined in any
> header, when I run doxygen I get output such as:
>
> Somepath/some_header.hpp:7: warning: documentation for unknown define
> MYLIB_SOME_MACRO found.
>
> In other words even though I want to include the documentation for the
> MYLIB_SOME_MACRO macro in my doxygen documentation it is rejected
> because the macro is never actually defined in any of the source files
> which doxygen parses.
>
> is there any way to tell doxygen to include the doxygen comments for the
> macro in its documentation even though the macro is not actually defined
> anywhere ?
>
>
You can include a definition of the macro surrounded by an ifdef guard
that won't be defined in normal compilation, but will be defined in your
doxygen config file. Then Doxygen will see that definition and document
it. I sometimes use the macro DOXYGEN for this. Something like:

#ifdef DOXYGEN
#define MYLIB_SOME_MACRO
#endif


--
Richard Damon


------------------------------------------------------------------------------
Find and fix application performance issues faster with Applications Manager
Applications Manager provides deep performance insights into multiple tiers of
your business applications. It resolves application problems quickly and
reduces your MTTR. Get your free trial!
https://ad.doubleclick.net/ddm/clk/302982198;130105516;z
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|

Re: Documenting macro which are not defined in the code

eldiener
On 4/26/2016 8:04 AM, Richard Damon wrote:

> On 4/26/16 3:37 AM, Edward Diener wrote:
>> In my library there are is a macro which, if defined at all by the
>> end-user, changes the way the code works. I want to include this macro
>> in the doxygen documentation to my library. So I add the doxygen comments:
>>
>> /** @file some_header.hpp
>>       @brief Some brief file description.
>>
>>       Some longer file description.
>> */
>>
>> /** @def MYLIB_SOME_MACRO
>>       @brief When this macro is defined at all, changes the way that xxx
>> works.
>>
>>       When this macro is defined at all xxx works in such and such way
>>       whereas when this macro is not defined xxx works in so and so way.
>> */
>>
>> Unfortunately because the macro itself is never actually defined in any
>> header, when I run doxygen I get output such as:
>>
>> Somepath/some_header.hpp:7: warning: documentation for unknown define
>> MYLIB_SOME_MACRO found.
>>
>> In other words even though I want to include the documentation for the
>> MYLIB_SOME_MACRO macro in my doxygen documentation it is rejected
>> because the macro is never actually defined in any of the source files
>> which doxygen parses.
>>
>> is there any way to tell doxygen to include the doxygen comments for the
>> macro in its documentation even though the macro is not actually defined
>> anywhere ?
>>
>>
> You can include a definition of the macro surrounded by an ifdef guard
> that won't be defined in normal compilation, but will be defined in your
> doxygen config file. Then Doxygen will see that definition and document
> it. I sometimes use the macro DOXYGEN for this. Something like:
>
> #ifdef DOXYGEN
> #define MYLIB_SOME_MACRO
> #endif

Thanks ! That works well.


------------------------------------------------------------------------------
Find and fix application performance issues faster with Applications Manager
Applications Manager provides deep performance insights into multiple tiers of
your business applications. It resolves application problems quickly and
reduces your MTTR. Get your free trial!
https://ad.doubleclick.net/ddm/clk/302982198;130105516;z
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users