Search code examples
makefiledocumentation-generation

How to document a makefile?


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.


Solution

  • 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).