Question

我有一个包含RPC可调用API的项目。该项目还包含一些其他代码。我想为这些API函数生成一个干净的文档（对于使用API的用户）。然而，仍然可以生成针对开发人员的整个程序的文档。

API分为几个类（“命令模块”）。我做的第一件事就是告诉Doxygen只看这些文件，当然。但是这些类也有一些代码，它们不是API的一部分，我想为（辅助函数）生成文档。

这些可调用函数（“命令”）具有特殊的返回类型：CommandResult。

例如，这是一个API类：

class CommandModuleFoo {
    int privateHelperFunction();
    int privateMember;

public:
    int publicHelperFunction();
    int publicMember;

public slots:
    /** Some documentation. */
    CommandResult myFunction1(int someArg);
    /** Some documentation. */
    CommandResult myFunction2();
};

现在文档基本上应该包含以下内容：

class CommandModuleFoo


公开会员：



CommandResult myFunction1(int someArg)

一些文档。



CommandResult myFunction2()

一些文档。

问题：

我知道只需在我INPUT的{{1}}变量中命名它们，我就只能选择项目文件的一部分。但我还可以使用模式选择一组函数吗？

由于我认为这是不可能的，我可以告诉Doxygen只生成一个部分的文档吗？ Doxygen有分段标记：Doxyfile ... \if可用于排除文档的某些部分，但包含它们的配置变量\endif。但我需要相反的观点。是否有类似ENABLED_SECTIONS的内容？

可能的解决方法：

除了我想要记录的命令之外，我可以在每个代码周围使用上述部分条件。但这听起来很难看。

我可以将ONLY_SECTION设置为HIDE_UNDOC_MEMBERS，以便仅为文档化成员生成文档，但如果有人想要，则无法生成该程序的完整文档。（即它禁止记录非API函数）。此外，检测未记录的API函数更加困难。

我目前正在使用第二种解决方法。

Answer 1

您可以执行以下操作：

在内部函数文档中使用\internal（本例中为非命令）：

/**
 * \internal
 * This helper function does foo.
 */
void myHelperFunction();

您的命令使用正常的doxygen注释：

/**
 * Some documentation.
 */
CommandResult myFunction();

然后，在您的Doxyfile中使用INTERNAL_DOCS = YES如果您编译整个程序的文档并INTERNAL_DOCS = NO（默认）来编译您的API文档。

基本上，将您的程序看作是一个库。库开发人员经常遇到这个问题：他们显然希望为库的用户提供一个干净的文档，其中只包含导出的东西，而他们（可能）也希望为库的开发人员提供更详细的文档。

PS。您还可以使用\internal有选择地包含函数文档的段落，即您的开发人员文档可能包含一些对API用户不重要的更多详细信息。有关详细信息，请参阅the documentation of \internal。

仅为某些成员函数生成doc

class CommandModuleFoo

1 个答案: