How to document makefile templates and include * .mk file interfaces?
We have several makefile templates that implement specific build actions by setting a few makefile parameter variables and applying the makefile template via include, for example
GENERIC_PARAM1-y := paramA
GENERIC_PARAM2-y := paramB
include $(MAKE_TOOLS)/doaction.mk
And files such as doaction.mk
contain make templates to generate standard rule definitions that apply if only an action step is included.
Now we want to document these interfaces for fragments *.mk
using Doxygen, for example
## @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 an easy way to achieve this using any Doxygen syntax / configuration?
source to share
"Is there an easy way to achieve this using any valid doxygen syntax / configuration?"
Yes, you can use doxygen settings INPUT_FILTER
, FILE_PATTERNS
and FILTER_SOURCE_FILES
how stolen from this blog post
Put these settings in config Doxyfile
FILE_PATTERNS = *.mk
INPUT_FILTER = "sed -e 's|##|//!|'"
FILTER_SOURCE_FILES = YES
INPUT_FILTER
actually does the trick, the command is sed
used by doxygen to open a pipe filtering input files by the specified command.
Note:
The above command is not built into the shell, so encoded command expressions such as
"grep '##' | sed -e 's|##|//!|'"
will not work.
Place your comments as suggested in the example ##
will expand for comments visible with 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 ...
Also, you must put
## @cond
...
## @endcond
around your makefile templates / code to avoid doxygen parsing those parts.
The above sample should look like this in the generated HTML documentation
source to share