How do you comment your makefiles?
cross-posted from: lemmy.ml/post/6863402
Fed up w/ my ad-hoc scripts to display the targets and variables in a makefile(s), I’ve decided to write a reusable piece of code to do that: 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
<span style="color:#323232;">VAR1 = foo ## short one-liner comment </span><span style="color:#323232;">my-target: ## short one-liner comment </span><span style="color:#323232;"> … </span>B
<span style="color:#323232;"># longer comment which </span><span style="color:#323232;"># may span </span><span style="color:#323232;"># several lines </span><span style="color:#323232;">VAR1 = foo </span><span style="color:#323232;"> </span><span style="color:#323232;">## comments can be prefixed w/ more than # </span><span style="color:#323232;">## lorem ipsum dolor </span><span style="color:#323232;">my-target: </span><span style="color:#323232;"> … </span>C
<span style="color:#323232;">##### </span><span style="color:#323232;"># a comment block which is marked w/ several #s on </span><span style="color:#323232;"># an otherwise blank line </span><span style="color:#323232;">##### </span><span style="color:#323232;">VAR1 = foo </span>D
<span style="color:#323232;">##### </span><span style="color:#323232;">#> # heading 1 </span><span style="color:#323232;"># This is a variation to have markdown comments </span><span style="color:#323232;"># inside makefile comments. </span><span style="color:#323232;"># </span><span style="color:#323232;"># ## It's a made-up style! </span><span style="color:#323232;"># I came up w/ this style and used it to document `bmakelib`. </span><span style="color:#323232;"># For example: https://is.gd/QtiqyA (opens github) </span><span style="color:#323232;">#< </span><span style="color:#323232;">##### </span><span style="color:#323232;">VAR1 = foo </span>