记录 CMake 脚本

我发现自己处于一种情况，我想准确记录大量自定义 CMake 宏和函数，并且想知道如何做到这一点。

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

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

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

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

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

这是我能得到的最接近的。以下是使用 CMake 2.8.10 进行测试的。目前，CMake 3.0正在开发中，它将获得基于CMake的新文档系统Sphinx http://sphinx-doc.org/ and 重构文本 http://de.wikipedia.org/wiki/ReStructuredText。我想这将带来记录模块的新方法。

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

第一行给出了模块的简要描述。它必须开始于-并以句号结束.或空行。

# - My first documented CMake module.
# description

或者 # - 我的第一个记录的 CMake 模块 # ＃ 描述

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

Example:

# - 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

Setting CMAKE_MODULE_PATH允许您定义其他目录来搜索模块。否则，您的模块需要位于默认的 CMake 位置。--help-custom-modules将文档生成限制为自定义、非 CMake 标准模块。如果您给出文件名，则文档将写入该文件，否则写入标准输出。如果文件名具有可识别的扩展名，则文档将采用相应的格式。

可以采用以下格式：

• .html用于 HTML 文档
• .1 to .9用于手册页
• .docbook对于文档书
• 其他任何内容：纯文本