Doxygen：如何正确记录具有 80 个字符限制的 C 结构成员变量？

Question

当您试图遵守 80 个字符的宽度限制时，是否有 proper/recommended 方法可以向 C struct 成员变量添加简短的 Doxygen 注释？

例如

// 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

在遵守 80 个字符的宽度限制的情况下，上述内容似乎不是记录 connLost_ 的正确方法：它最终会在 "Field Documentation" 小节下生成 connLost 的描述而不是连同其对等成员变量。

#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

这是错误的不同之处：虽然 connLost_ 与其同行一起记录，但 "connection" 一词（反斜杠后的所有内容）从文档中删除。

#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

这也不是我想要的：connLost_ 的文档可以追溯到 "Field Documentation" 部分，而不是与其同行一起。

如图所示，我想以 "doxygen-native" 的方式实现：

Answer 1

你在第二个例子中做的没问题。您只需添加一个 \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

Doxygen：如何正确记录具有 80 个字符限制的 C 结构成员变量？

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

c

doxygen