Q: Doxygen doesn't distinguish between `union myname` and `struct myname` I've written a small matrix library as part of a larger project I am working on. It was important to have zero-cost transpositions, so I used/abused unions. The code itself works fine (provided below), but when it came to document with Doxygen, it combines all of the documentation for both struct matrix_r and union matrix_r into a single item. That is, there are only generated pages for struct matrix_r and struct matrix_c, but those two pages describe matrix_r and matrix_c as unions, with concatenated @brief text and concatenated attributes (from both the struct and union declarations).
I am very, very new to Doxygen, but I have been unable so far to figure out how to get it to treat these as separate documentation items. Any ideas?
#include <stddef.h>

/// @brief internal stuct for row-major matrices
struct matrix_r {
    int *data; ///< raw pointer backing matrix
    size_t m;  ///< the number of rows
    size_t n;  ///< the number of cols
};

/// @brief internal struct for col-major matrices
struct matrix_c {
    int *data; ///< raw pointer backing matrix
    size_t n;  ///< the number of cols
    size_t m;  ///< the number of rows
};

/// @brief user-facing typedef for row-major matrices
typedef union {
    struct matrix_r id;   ///< identity view of matrix
    struct matrix_c tr;   ///< transposed view of matrix
    int*            flat; ///< flattened view of matrix
} matrix_r;

/// @brief user-facing typedef for row-major matrices
typedef union {
    struct matrix_c id;   ///< identity view of matrix
    struct matrix_r tr;   ///< transposed view of matrix
    int*            flat; ///< flattened view of matrix
} matrix_c;


A: Structural commands start with a backslash (\), or (@) followed by a command name and one or more parameters. For instance, if you want to document the class Test , you could have put the following documentation block somewhere in the input that is read by doxygen:
/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

Straight from the manual, here are some other commands:

Here the special command \class is used to indicate that the comment
  block contains documentation for the class Test. Other structural
  commands are:
\struct to document a C-struct.
\union to document a union. 
\enum to document an enumeration type. 
\fn to document a function. 
\var to document a variable or typedef or enum value. 
\def to document a #define. 
\typedef to document a type definition. 
\file to document a file. 
\namespace to document a namespace. 
\package to document a Java package. 
\interface to document an IDL interface.


Edit: 
I believe this is the way Doxygen is designed to work.  See the 
documentation here: 
http://www.doxygen.nl/autolink.html
in the section "typedefs".  It says: 

Typedefs that involve classes, structs and unions, like 
typedef struct StructName TypeName 
create an alias for StructName, so links will be generated to 
  StructName, when either StructName itself or TypeName is  encountered.

Doxygen considers the union tag name to be "the real thing", 
not the typedef (which is considered like an alias of "the real 
thing"). I'd recommend this:
/*!@brief The documentation of the union Name*/ 
typedef union Name 
{ 
    //..... 
}Name; 

