Doxygen - Document a struct variable but not the struct

Question

Let's say I have this struct type:

typedef struct Hidden Hidden;
struct Hidden
{
    int foo;
    int bar;
};

and then I have a global variable

Hidden visible;

Hidden should never be used and visible should be the only declaration of type Hidden. I don't want to generate documentation for Hidden as I don't want it to be used, but instead generate documentation for visible with all the information about it and about its fields.

The closest thing I've found is that when you document a struct with no tag like:

struct
{
    int foo; ///< Number of particals in the universe.
    int bar; ///< Number of socks in the drawer.
} Baz; ///< Nameless struct variable.

Doxygen will generate

struct {
   int foo
       Number of particals in the universe. 
   int bar
       Number of socks in the drawer. 
} Baz
  Nameless struct variable.

This is the sort of thing I'm trying to achieve, but I can't use nameless structs.

Is such thing possible?

Avidan Borisov · Accepted Answer · 2013-03-07T20:54:37.473

4

I've found a way to do it. Using proprocessor predefines as @RBE suggested lets you create code only for doxygen which won't compile anyway. So just do this (and make DOXYGEN a predefined macro):

typedef struct Hidden Hidden;

#ifdef DOXYGEN

struct
{
    int foo; ///< Number of particals in the universe.
    int bar; ///< Number of socks in the drawer.
} visible; ///< Nameless struct variable!

#endif

struct Hidden
{
    int foo;
    int bar;
};

Hidden visible;

It's hacky, but it works.

edited Mar 07 '13 at 20:54

answered Mar 07 '13 at 20:43

Avidan Borisov

3,235
4
24
27

1

Just a note here - it is strongly recommended not to leave undocumented parts of your API especially if the contents of the undocumented functions/enums/structs/etc. are actually documented. – rbaleksandar Feb 16 '17 at 13:13

RBE · Answer 2 · 2013-03-07T20:24:35.820

0

The simplest way to do what you want is to use a macro definition to switch between the code you will compile, and the code you will run doxygen on:

#define DOXYGEN

#ifdef DOXYGEN
/**
 *  @brief Describe your visible structure here.
 */
typedef struct VISIBLE
{
    int foo; //< Number of particles in the universe.
    int bar; //< Number of socks in the drawer.
} VISIBLE;
#else
typedef struct HIDDEN
{
    int foo;
    int bar;
} HIDDEN;

HIDDEN visible;
#endif

Simply comment or uncomment the DOXYGEN definition to switch from one to the other.

edited Mar 07 '13 at 20:24

answered Mar 07 '13 at 20:10

RBE

175
1
11

You misunderstood me. I don't want to just change the name of the structure from HIDDEN to VISIBLE. I want to generate documentation just to a single struct variable instead of documentation for the struct type itself. – Avidan Borisov Mar 07 '13 at 20:33

Doxygen - Document a struct variable but not the struct

2 Answers2