How to document makefile templates and include *.mk file interfaces?

Question

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?

Answer 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