问题
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
And files like doaction.mk contain make templates to generate standard rule definitions that are applied when just including the action make step.
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 ...
Is there a simple way to achieve this using any valid Doxygen syntax/configuration?
回答1:
"Is there a simple way to achieve this using any valid doxygen syntax/configuration?"
Yes, you can use doxygen's INPUT_FILTER, FILE_PATTERNS and FILTER_SOURCE_FILES configuration settings as stolen from this blog post
Put these settings in your Doxyfile configuration
FILE_PATTERNS = *.mk
INPUT_FILTER = "sed -e 's|##|//!|'"
FILTER_SOURCE_FILES = YES
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|##|//!|'"
won't work.
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 ...
Additionally you should put a
## @cond
...
## @endcond
around your makefile rules/templates code, to avoid doxygen parsing these parts.
The above sample should render as follows in the generated documentation HTML
来源：https://stackoverflow.com/questions/26874238/how-to-document-makefile-templates-and-include-mk-file-interfaces