Issue getting Doxygen to document an enum in C

问题:

I have a rather odd problem with Doxygen (1.6.1 on Mac OS X Snow Leopard) in that it does not seem to document my enums no matter what I do. I am programming in C and have followed the instructions in the manual. Here is my code:

/**
 * \enum dccp_pkt_type 
 * \brief specifies the available DCCP packet types
 */

enum dccp_pkt_type
{
    DCCP_REQUEST    = 0,    /**< DCCP Request Packet */
    DCCP_RESPONSE,          /**< DCCP Response Packet */
    DCCP_DATA,              /**< DCCP Data Packet */
    DCCP_ACK,               /**< DCCP Ack Packet */
    DCCP_DATAACK,           /**< DCCP Data Ack Packet */
    DCCP_CLOSEREQ,          /**< DCCP Close Request Packet */
    DCCP_CLOSE,             /**< DCCP Close Packet */
    DCCP_RESET,             /**< DCCP Reset Packet */
    DCCP_SYNC,              /**< DCCP Sync Packet */
    DCCP_SYNCACK,           /**< DCCP Sync Ack Packet */
    DCCP_RESERVED,          /**< DCCP Reserved Packet Type - Receivers MUST
                         ignore any packets with this type */
};

It should according to the doxygen manual produce properly documentated output but instead it produces nothing. I am most likely missing something simple, if anyone could point me in the right direction I would be grateful.

回答1:

From the Doxygen manual:

Let’s repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

/*! \file */ or a

/** @file */ line in this file.

回答2:

My experience is the same using EXTRACT_ALL=NO and SHOW_INCLUDE_FILES=NO with doxygen 1.8.9.1 - global enum types were not listed nor linked even though /*! \file */ is present and the global enum is referenced by a documented compound structure.

To work around this, I ended up defining an Enumerations group:

/*! \defgroup Enumerations Public enumeration types */

and for the enum types I used \ingroup Enumerations to include the enums in the new group. Doxygen then was able to autolink from the compound structures to the enum types.

回答3:

If memory serves correctly, enum documentation doesn't show up unless the file is also documented. Try adding a @file section.