doxygen-users

[Doxygen-users] doxygen #define question

[<hew...@gm...>]

Hi there!  I have a question regarding the doxygen preprocessor.  In some of my code (.c) modules I have a #define setup to tell the .h file for that module how to behave.  For example in the following file (driver.c) I define the constant CDR:


#define CDR
#include "driver.h"


/**
 @brief Initialize all CAN1 Driver variables.
 @return none
*/
void initialize(void)
{
 //! @todo Run some code here...
 printf("%d", test_file_scope_variable);
}


Then in the header file (driver.h), I perform certain actions based on whether CDR has been defined.  For example, the static variable test_file_scope_variable below is only declared if CDR is defined.


#ifdef CDR /* LOCAL definition */


/**
 @var test_file_scope_variable
  File Scope variable to Test doxigen
*/
static u16 test_file_scope_variable;


#endif /* CDR */


All the above code works great at the compiler level but when I go to run doxygen the documentation generated never shows test_file_scope_variable since doxygen can't seem to see that CDR has been defined in the C module.  Does anyone know how to solve this?  I know that I can solve this by defining CDR using the PREDEFINED setting in the doxygen settings.  However this will define CDR for the whole project and I only want it defined only for this module and header combination.



Thanks!  Any help would be greatly appreciated!



-Joe

Re: [Doxygen-users] doxygen #define question

[Dimitri v. H. <do...@gm...>]

On 09 Jan 2014, at 5:56 , hew...@gm... wrote:

> Hi there!  I have a question regarding the doxygen preprocessor.  In some of my code (.c) modules I have a #define setup to tell the .h file for that module how to behave.  For example in the following file (driver.c) I define the constant CDR:
> 
> #define CDR
> #include "driver.h"
> 
> /**
>  @brief Initialize all CAN1 Driver variables.
>  @return none
> */
> void initialize(void)
> {
>  //! @todo Run some code here...
>  printf("%d", test_file_scope_variable);
> }
> 
> Then in the header file (driver.h), I perform certain actions based on whether CDR has been defined.  For example, the static variable test_file_scope_variable below is only declared if CDR is defined.
> 
> #ifdef CDR /* LOCAL definition */
> 
> /**
>  @var test_file_scope_variable
>   File Scope variable to Test doxigen
> */
> static u16 test_file_scope_variable;
> 
> #endif /* CDR */
> 
> All the above code works great at the compiler level but when I go to run doxygen the documentation generated never shows test_file_scope_variable since doxygen can't seem to see that CDR has been defined in the C module.  Does anyone know how to solve this?  I know that I can solve this by defining CDR using the PREDEFINED setting in the doxygen settings.  However this will define CDR for the whole project and I only want it defined only for this module and header combination.

Doxygen assumes that header files are self-contained and protected against multiple inclusion (with guards or #pragma once).
This is usually considered a good design practice. 

You header "driver.h" doesn't comply with this assumption as it requires CDR to be defined some somewhere outside the file. 
There is not really a good solution. Basically you want to document two "versions" of one header file (with and without CDR defined).
Maybe it is better to put the CDR related driver stuff in a driver_cdr.h header that is only included from driver.c?

Regards,
  Dimitri