Documenting a typedef'd struct with specified pointer using dOxygen?

Question

I have a struct something like:

/**
*  Typical dOxygen brief about the typedef. Longer description follows.
*/
typedef struct _SOME_STRUCT_TAG {
    int var1; /**< Something useful. */
    int var2; /**< something equally useful. */
} SOME_STRUCT_T, *LPSOME_STRUCT_T /**< A post doc the pointer here. Longer description follows */;

I've enabled the project option TYPEDEF_HIDES_STRUCT.

I'd like the documentation to create two separate entries: one for the pointer typedef and one for the non-pointer typedef. Currently, I only seem to get one for the pointer typedef.

What am I doing wrong here? I'm also open to general syntax suggestions. Note this is for a C library, not C++. It seems dOxygen has trouble dealing with a typedef which has multiple statements (ie typedef int var_t,*pvar_t).

By the way, the typedef is not required in C++, which is one of many differences between C++ and C. — Thomas Matthews

Ben Voigt Ben Voigt · Accepted Answer · 2014-06-24T14:00:21

IIRC, doxygen doesn't support different documentation for multiple identifiers in a single declaration at all. So separate them.

Instead of

int a, b, c;

use

int a;
int b;
int c;

and instead of

typedef struct _SOME_STRUCT_TAG {
    int var1; /**< Something useful. */
    int var2; /**< something equally useful. */
} SOME_STRUCT_T, *LPSOME_STRUCT_T;

use

typedef struct _SOME_STRUCT_TAG {
    int var1; /**< Something useful. */
    int var2; /**< something equally useful. */
} SOME_STRUCT_T;
typedef SOME_STRUCT_T *LPSOME_STRUCT_T;

Also note that you're using reserved words for struct and typedef names, which is inviting trouble, not only from doxygen.

Also, this practice of transparent typedef names for pointers is bad style. If the pointer type is an opaque handle and clients will never see the underlying type, or even know that the handle is a pointer (as opposed to a table index or other key), use a typedef. If the client works directly with the structure, let them use SOME_STRUCT_T *.

Documenting a typedef'd struct with specified pointer using dOxygen?

1 Answers