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

Question

C struct当您尝试遵守 80 个字符的宽度限制时，是否有适当/推荐的方法向成员变量添加简短的 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

上面的内容似乎不是connLost_遵守 80 个字符宽度限制的正确记录方式：它最终会在“字段文档”小节下生成描述，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_与同行一起记录，但“连接”一词（反斜杠后面的所有内容）从文档中删除了。

#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_的文档回到“现场文档”部分，而不是与其同行一起。

如图所示，我想以“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