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

Question

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:

Have you considered putting a line break between MQTTAsync_connectionLost and connLost_? — Draconis
– Draconis, Commented May 14, 2019 at 2:51
@Draconis - I did, and I'm not opposed to that (but it's not my preferred solution), but I'd like to learn if there's a "doxygen-native" solution to this. — StoneThrow
– StoneThrow, Commented May 14, 2019 at 2:52

Cristian Bidea · Accepted Answer · 2019-05-14 06:59:44Z

6

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

answered May 14, 2019 at 6:59

Cristian Bidea

7094 silver badges16 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

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

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related