标签: doxygen

我想知道在 doxygen 中记录以下内容的正确方法是什么。

有一个定义一些验证器的类，例如：

class Validators {
    /**
    * @fn A
    * @brief sees if x is too large.
    * @param[in] x the input to validate
    * @throws runtime_error when otx is too large.
    */
    static void A(int x) {
        if (x > 5) {
            throw std::runtime_error("x too large");
        }
    }
};

在如下函数中使用此验证器：

#include "validator.h"

class MyClass {
public:
    void setX(int x) {
        Validators::A(x);
    }
};

我应该如何记录setX()重新抛出由 引发的runtime_error A()，或者我根本不应该记录它？

我正在将 doxygen 用于我的个人项目，并希望在我自己创建的页面（markdown 页面）上使用任何类型的 UML 语言。我并不是想在代码中使用它（它确实有效），而是在我自己创建的文档上，请参阅下面的示例：

# Example

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
```

```mermaid
sequenceDiagram
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> …

Doxygen@retval提供了一种清晰的方法来记录多个返回值：

/**
 * Do the thing to the other thing.
 *
 * @param[in] other_thing The thing to do it to.
 *
 * @retval STATUS_OK on success.
 * @retval STATUS_BAD_ARGS if the other thing wasn't right.
 * @retval STATUS_TIMED_OUT if the thing timed out.
 */
status_t do_the_thing(thing_t other_thing);

但是如果通过输出参数返回该状态怎么办？是否有记录这些值的约定？

/**
 * Do a couple things to the other thing.
 *
 * @param[in] other_thing The thing to do it to.
 * @param[out] out_status_1 The status of the first thing done. …

我正在尝试使用 CMake 来生成 Doxygen 文档。这是我的 CMakeList.txt 的样子：

if (DOXYGEN_FOUND)
    # set input and output files
    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/config-file)
    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}doc)

    # request to configure the file
    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
    message("Doxygen build started")

    # note the option ALL which allows to build the docs together with the application
    add_custom_target( doc_doxygen ALL
        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "Generating API documentation with Doxygen"
        VERBATIM )
else (DOXYGEN_FOUND)
  message("Doxygen need to be installed to generate the doxygen documentation")
endif (DOXYGEN_FOUND)

运行后make，我收到以下错误：

Doxygen …

我想在我的项目中使用 doxygen 来生成文档。

我的项目的所有“正常”依赖项均由 vcpkg 管理，我希望我也可以通过这种方式使用 doxygen，尽管它不是我链接的库，而是我用来处理文件的工具。

• 似乎有一些必要，因为这个问题似乎已发布并且一些解决方案已合并。
• 当我进一步挖掘时，我发现有一个名为vcpkg_find_acquire_program的函数，可以专门使用 doxygen 参数来调用。但是，所有示例都使用了portfile.cmake我的项目所没有的。

在我的项目中我使用：

• vcpkg.json 充当清单文件。我指定项目名称、版本、依赖项。但我无法将 doxygen 放入依赖项列表中，因为没有 doxygen portfile
• CMakeLists.txt 我可以在其中指定我需要 doxygen，但 cmake 不会为我管理下载/安装它。这是 vcpkg 的工作。
• CMakeSettings.json 我在其中指定构建配置

...这就是项目配置方面的内容。那么，我应该把 vcpkg_find_acquire_program 放在哪里？或者有什么不同的方法吗？

假设我想/* - */在 C++ 代码的 Doxygen 文档块中的代码块内显示分隔注释块。如果 Doxygen 块本身是/* - */ 分隔的，就像这样，

/**
    documentation
    \code
    /*
        comment 
    */
    \endcode
*/

这显然会成为一个问题：Doxygen 会做正确的事情，但 C++ 编译器不知道它应该忽略内部*/. 另一种方法是使用 ///- 分隔的 Doxygen 块：

/// documentation
/// \code
/// /*
///     comment 
/// */
/// \endcode

这个版本不会让 C++ 编译器感到困惑，但现在 Doxygen 添加了一个额外的星号。我怎样才能让 Doxygen 和 C++ 都满意？

评论中建议我至少可以将额外的星号与应该存在的星号对齐，使输出看起来更好。在某些情况下这可能是可以接受的，但我认为这对我来说是一个问题，所以让我解释一下原因。该文档正在讨论一种渲染器着色语言，它可以理解#include单行注释，但不能理解块注释，并且想说：

不支持块注释行，但如果包含的文件未关闭块，则可能无关紧要：

/*
  #include "MyFile.h" --> file will be included anyway.
*/

Run Code Online (Sandbox Code Playgroud)

如果改为

/*
 *  #include "MyFile.h" --> file will be included …

Run Code Online (Sandbox Code Playgroud)

确切地说:我知道如何在声明时使用dox枚举,我想把它们排除在外.

我想保持头文件没有doxygen评论; 它们都在.cpp文件中.对于函数,类,typedef等,这不是问题.我也可以这样记录enum自己:

/*!
  \enum MyClass::MyEnum

  Foo Bar Baz

  \value FirstEnumValue <- doesn't work
*/

但我怎么记录的值的enum呢？

谢谢!

我正在尝试使用Doxygen记录类属性.目前,受保护的属性显示在特定类的页面顶部的列表中.我想为他们解释一下.

我已尝试@param [name] [description]在类的开头上方和属性声明的正上方使用它们.我甚至尝试将它们放入我的构造函数类的docblock中,它就破坏了它.

有什么东西我只是缺少？

- 洛根

鉴于一些包装foo.bar.project.something.FirstModule foo.bar.project.something.SecondModule等,它们都有很长foo.bar.project.something的共同点.我如何告诉doxygen隐藏(或至少缩短)这些常见的包名,只打印FirstModule.SomeClass并SecondModule.MyInterface在其输出中？

所以我有一个简单的功能以及一些文档：

/**
 *  @param[out] dest is overwritten by the second argument
 *  @param[in] src is value to overwrite the first argument with
 */
void Copy(int &dest, int src) { dest = src; }

可能不是很有用，但很明显它dest是输出。但是，使用指针对我来说，这条线变得模糊了：

void Copy(int *dest, int src) { *dest = src; }

应该dest还是输出？指针的值不会被修改，只有指针指向的内存中的值会被修改。但是我仍然会说是的。继续：

void Write(FILE *fw, int src) { fwrite(&src, sizeof(src), 1, fw); }

现在这对我来说确实fw是个问题，尽管在逻辑上它是输出，但我仍将其标记为输入，并且FILE结构的内容也会在此过程中被修改（但对我而言这是相当不透明的）。

另一方面：

void Open(FILE &*fw, const char *filename) { fw = fopen(filename, "w"); }

显然是输出。所述FILE …