Question

Is there a way to write “standard” comments in a Makefile to later feed them to a Doxygen-like program so as to output a nice (HTML or man for instance) documentation ? I’d like to have a clear overview of my main targets somewhere but nothing too fancy.

Answer 1

One nice touch is to provide a phony help target that prints a summary of targets and options. From the Linux kernel Makefile:

help:
        @echo  'Cleaning targets:'
        @echo  '  clean           - Remove most generated files but keep the config and'
        @echo  '                    enough build support to build external modules'
        @echo  '  mrproper        - Remove all generated files + config + various backup files'
        @echo  '  distclean       - mrproper + remove editor backup and patch files'
        @echo  ''
        @echo  'Configuration targets:'
        @$(MAKE) -f $(srctree)/scripts/kconfig/Makefile help
        @echo  ''

It might be a bit of work to maintain the documentation this way, but I find it nicely separates what is intended for “users” versus what is intended for people maintaining the Makefile itself (inline comments).