如何记录makefile模板并包括* .mk文件接口? [英] How to document makefile templates and include *.mk file interfaces?

问题描述

我们有许多makefile模板，这些模板通过设置一些参数makefile变量并通过像这样的包含来应用makefile模板，从而实现某些构建动作

We have a number of makefile templates, that realize certain build actions by setting a few parameter makefile variables, and applying a makefile template via inclusion like

GENERIC_PARAM1-y := paramA
GENERIC_PARAM2-y := paramB

include $(MAKE_TOOLS)/doaction.mk

doaction.mk之类的文件包含make模板，以生成标准规则定义，这些规则定义仅在包括动作make步骤时应用.

And files like doaction.mk contain make templates to generate standard rule definitions that are applied when just including the action make step.

现在，我们要使用Doxygen之类的文档来记录*.mk片段的这些接口

Now we want to document these interfaces for the *.mk snippets using Doxygen like

## @file
## @brief doaction.mk is purposed to ...
## 
## Some more detailed descriptions about rules applied ...
## @param GENERIC_PARAM1-y Parameter1 description ...
## @param GENERIC_PARAM2-y Parameter2 description ...

是否有使用任何有效的Doxygen语法/配置来实现此目标的简单方法?

Is there a simple way to achieve this using any valid Doxygen syntax/configuration?

推荐答案

是否有一种简单的方法可以使用任何有效的doxygen语法/配置来实现这一目标?"

是的，您可以使用doxygen的INPUT_FILTER，FILE_PATTERNS和FILTER_SOURCE_FILES配置设置

Yes, you can use doxygen's INPUT_FILTER, FILE_PATTERNS and FILTER_SOURCE_FILES configuration settings as stolen from this blog post

将这些设置放入您的Doxyfile配置

Put these settings in your Doxyfile configuration

FILE_PATTERNS = *.mk 
INPUT_FILTER = "sed -e 's|##|//!|'" 
FILTER_SOURCE_FILES = YES 

INPUT_FILTER实际上可以解决问题，doxygen使用sed命令打开一个沿指定命令过滤输入文件的管道.

The INPUT_FILTER actually does the trick, the sed command is used by doxygen to open a pipe filtering the input files along the specified command.

注意:
上面提到的命令没有嵌入到外壳程序中，因此像

Note:
The above mentioned command isn't embedded into a shell, thus chained command statements like

"grep '##' | sed -e 's|##|//!|'"

不起作用.

按照样本##中的建议放置您的评论，以扩大doxygen看到的评论

Put your comments as proposed in the sample ## will expand for comments seen by doxygen

## @file
## @brief doaction.mk is purposed to ...
## 
## Some more detailed descriptions about rules applied ...
## @param GENERIC_PARAM1-y Parameter1 description ...
## @param GENERIC_PARAM2-y Parameter2 description ...

另外，您应该放置

## @cond
...
## @endcond

围绕您的makefile规则/模板代码，以避免doxygen解析这些部分.

around your makefile rules/templates code, to avoid doxygen parsing these parts.

以上示例应在生成的文档HTML中呈现如下

The above sample should render as follows in the generated documentation HTML

这篇关于如何记录makefile模板并包括* .mk文件接口?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！