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

【问题标题】：Doxygen: How to properly document a C struct member variable with 80-char limit?Doxygen：如何正确记录具有 80 个字符限制的 C 结构成员变量？
【发布时间】：2019-05-14 02:43:17
【问题描述】：

当您尝试遵守 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_ 与它的同行一起记录，但“连接”一词（反斜杠后的所有内容）都从文档中删除。

#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”的方式，从图片上看，我想要实现的目标：

【问题讨论】：

您是否考虑过在MQTTAsync_connectionLost 和connLost_ 之间设置换行符？
@Draconis - 我做到了，我不反对（但这不是我的首选解决方案），但我想了解是否有“doxygen-native”解决方案。

标签： c doxygen

【解决方案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

【讨论】：