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

Question

当您尝试遵守80个字符的宽度限制时，是否有适当/推荐的方式在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_的正确方法：最终会在“字段文档”小节下生成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_的文档可以回溯到“现场文档”部分，而不是与之同行。

在图片上，我想以“纯氧”方式实现：

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