Question

我发现自己处于一种情况，我想准确地记录一系列自定义CMake宏和函数，并且想知道如何去做。

首先想到的是简单地使用内置语法和文档脚本，如下所示：

# -----------------------------
# [FUNCTION_NAME | MACRO_NAME]
# -----------------------------
# ... description ...
# -----------------------------

这很好。但是，我想使用常见的文档生成器，例如doxygen，来生成外部文档，任何人都可以阅读，而无需查看实现（这是常见的场景）。

一种方法是编写一个简单的解析器，直接从CMake脚本生成相应的C / C ++头文件及相应的签名和文档，可以通过doxygen或类似的工具进行处理。人们也可以手工维护这样的标题 - 这显然是单调乏味且容易出错。

有没有其他方法可以使用带有CMake脚本的文档生成器？

Answer 1

这是我能得到的最接近的。使用CMake 2.8.10测试以下内容。目前，CMake 3.0正在开发中，它将获得基于Sphinx和reStructuredText的新文档系统。我想这会带来记录模块的新方法。

CMake 2.8可以从您的模块中提取文档，但只考虑文件开头的文档。所有文档都以CMake注释的形式添加，从单个#开始。双##将被忽略（因此您可以在文档中添加注释）。文档的结尾由第一个非注释行标记（例如空行）

第一行简要介绍了该模块。它必须以-开头，以句号.或空白行结束。

# - My first documented CMake module.
# description

或＃ - 我的第一个记录的CMake模块＃＃description

在HTML中，以两个或多个空格开头的行（#之后）用等宽字体格式化。

示例：

# - My custom macros to do foo
#
# This module provides the macro foo().
# These macros serve to demonstrate the documentation capabilietes of CMake. 
#    
#    FOO( [FILENAME <file>]
#         [APPEND]
#         [VAR <variable_name>]
#    )
#
# The FOO() macro can be used to do foo or bar. If FILENAME is given, 
# it even writes baz. 

MACRO( FOO )
 ...
ENDMACRO()

要仅为自定义模块生成文档，请调用

cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html

设置CMAKE_MODULE_PATH允许您定义其他目录以搜索模块。否则，您的模块需要位于默认的CMake位置。 --help-custom-modules将文档生成限制为自定义的非CMake标准模块。如果您提供文件名，则文档将写入文件，否则写入stdout。如果文件名具有已识别的扩展名，则相应地格式化文档。

以下格式是可能的：

.html用于HTML文档
.1至.9
.docbook for Docbook
其他：纯文字

记录CMake脚本

1 个答案: