CODEWITHSUNDEEP
cdoxygen
StoneThrow
StoneThrow

Reputation: 6295

Doxygen: How to properly document a C struct member variable with 80-char limit?

Is there a proper/recommended way to add a short Doxygen comment to a C struct member variable when you're trying to obey an 80-char width-limit?

E.g.

// MyStruct.h

#ifndef MY_H
#define MY_H

typedef struct MyStruct
{
  struct in
  {
    int i_;                             ///< A number
    MQTTAsync_connectionLost connLost_; ///< Callback invoked upon loss of
                                        ///< connection
    char c_;                            ///< A letter
  } in_;
} MyStruct;

#endif

The above doesn't seem the right way to document connLost_ while obeying an 80-char width limit: it ends up generating the description of connLost under a "Field Documentation" subsection instead of along-with its peer member variables.

#ifndef MY_H
#define MY_H

typedef struct MyStruct
{
  struct in
  {
    int i_;                             ///< A number
    MQTTAsync_connectionLost connLost_; ///< Callback invoked upon loss of \
                                             connection
    char c_;                            ///< A letter
  } in_;
} MyStruct;

#endif

That is wrong differently: although connLost_ is documented along with its peers, the word "connection" (everything after the backslash) is dropped from the documentation.

#ifndef MY_H
#define MY_H

typedef struct MyStruct
{
  struct in
  {
    int i_;                             ///< A number
    /** Callback invoked upon loss of connection */
    MQTTAsync_connectionLost connLost_;
    char c_;                            ///< A letter
  } in_;
} MyStruct;

#endif

That isn't what I want either: connLost_'s documentation goes back to being in the "Field Documentation" section instead of along with its peers.

Pictorially, what I'd like to achieve, in a "doxygen-native" manner: enter image description here

Upvotes: 4

Views: 5945

Answers (1)

Cristian Bidea
Cristian Bidea

Reputation: 709

What you did in the second example is ok. You just have to include a \brief!

#ifndef MY_H
#define MY_H

typedef struct MyStruct
{
  struct in
  {
    int i_;                             ///< A number
    // NOTE THE BRIEF HERE
    /** \brief Callback invoked upon loss of connection */
    MQTTAsync_connectionLost connLost_;
    char c_;                            ///< A letter
  } in_;
} MyStruct;
#endif

Upvotes: 6

Related Questions