Hey Braham, you might be interested in these:
- makehelp, a Perl script that is a bit like a little Doxygen for your Makefiles. https://github.com/christianhujer/makehelp I created it 9 years ago. - Or just this: .PHONY: clean ## clean: Removes all generated files. clean:: $(RM) *.[adios] .PHONY: help ## help: Prints this help text. help: sed -n 's/^## \?//p' $(MAKEFILE_LIST) I first document for the user, want that `make help` tells users how to use the Makefile. And that would typically be displayed on the command line, when someone types `make help`. I usually don't document my variables or targets from an implementation perspective, I try to use good, that is, self-documenting, intent-communicating symbol names. Best regards, Christian On Sun, Oct 22, 2023 at 10:14 PM Bahman Movaqar <bah...@bahmanm.com> wrote: > Hey all, > > Fed up w/ my ad-hoc scripts to display the targets and variables in a > makefile(s), I've decided [1] to write a reusable piece of code to do > that: https://github.com/bahmanm/bmakelib/issues/81 > > The first step toward that would be to understand the common commenting > styles. So far I have identified 4 patterns in the wild which you can > find below. > > Are there any style guides/conventions around this topic? Any references > to well-written makefiles I can get inspiration from? > > > ―――――――――――――――――――― A ――――――――――――――――――――――――― > > VAR1 = foo ## short one-liner comment > my-target: ## short one-liner comment > … > > > ―――――――――――――――――――― B ――――――――――――――――――――――――― > > # longer comment which > # may span > # several lines > VAR1 = foo > > ## comments can be prefixed w/ more than # > ## lorem ipsum dolor > my-target: > … > > > ―――――――――――――――――――― C ――――――――――――――――――――――――― > > ##### > # a comment block which is marked w/ several #s on > # an otherwise blank line > ##### > VAR1 = foo > > > ―――――――――――――――――――― D ――――――――――――――――――――――――― > > ##### > #> # heading 1 > # This is a variation to have markdown comments > # inside makefile comments. > # > # ## It's a made-up style! > # I came up w/ this style and used it to document `bmakelib`. > # For example: https://is.gd/QtiqyA (opens github) > #< > ##### > VAR1 = foo > > > -- > Bahman > > Join the chatter on Matrix: > 🗣️ https://matrix.to/#/#.mk:matrix.org > > Subscribe to the Lemmy community: > 🐭 https://lemmy.ml/c/makefile > > > > > -- Christian Hujer CEO/CTO Nelkinda Software Craft Pvt Ltd 📧 Christian Hujer <christian.hu...@nelkinda.com> | 𝕏 @nelkinda <https://twitter.com/nelkinda> | 🌐 https://nelkinda.com ☏ 🇮🇳 ✆ +91 77 2003 6661 <+917720036661>
