Re: Doxygen-style documentation for Makefiles

[John Dill]

>Message: 1
>Date: Fri, 2 Apr 2021 13:25:19 +0530
>From: Christian Hujer <christian.hujer@nelkinda.com>
>To: help-make@gnu.org
>Subject: Doxygen-style documentation for Makefiles
>Message-ID:
>        <CAFh9tEc6pdJ_X5qx8uikZtbZFeSnS7RvmS2m+9jA0_Uj9nH=jg@mail.gmail.com>
>Content-Type: text/plain; charset="UTF-8"
>
>Hello everyone,
>
>I have, already years ago, created a doxygen-style documentation tool
>for Makefiles.
>It allows documenting variables and targets using ## (double-hash) comments.
>These comments can then be accessed by running the tool, preferably
>via a command like make help.
>I hope this tool is useful for others, and I'm posting it here so that
>if people are searching this mailing list for such a tool, they may
>have a chance to find it.
>
>Find the tool here: https://github.com/christianhujer/makehelp

Cool, I had gone through the trouble of making a make2c.sed script that
would convert (… cough hack...) the syntax to C syntax, then run it in
doxygen-config using the INPUT_FILTER "sed -f make2c.sed".  Works ok,
but I never could really get doxygen parsing figured out enough to make
'make' an official doxygen supported language.

Appreciate the link.  If I ever find myself motivated to work on my
make library again, I'll check this out.

This is an example of how I created a comment block.

#!
# \brief Find all instances of a set of words in a list.
# \param $1 The words.
# \param $2 The list.
# \return A set of indices that point to the words referenced by
#         \mkarg{1} in list \mkarg{2}.
#
# \usage
# \include list/word_index_example.mk
#
# The example above should display the following.
#
# \code
# alphabet "a b c d e f g h i j k l m n o p q r s t u v w x y z"
# word_index(hello,alphabet) = 8 5 12 12 15
# word_index(world,alphabet) = 23 15 18 12 4
# word_index(programming,alphabet) = 16 18 15 7 18 1 13 13 9 14 7
# word_index(make,alphabet) = 13 1 11 5
# word_index(extension,alphabet) = 5 24 20 5 14 19 9 15 14
# word_index(library,alphabet) = 12 9 2 18 1 18 25
#
# colors "white red orange yellow green blue violet brown black"
# flags "britain canada france germany ireland italy mexico united_states"
# word_index(britain,colors) = 6 1 2
# word_index(canada,colors) = 1 2
# word_index(france,colors) = 6 1 2
# word_index(germany,colors) = 9 2 4
# word_index(ireland,colors) = 5 1 3
# word_index(italy,colors) = 5 1 2
# word_index(mexico,colors) = 5 1 2 8
# word_index(united_states,colors) = 2 1 6
# \endcode
#/
word_index=$(_mxl_tr2)$(strip \
$(foreach iter,$1,\
  $(foreach jter,$(call generate_index,$(words $2)),\
    $(if $(call eq,$(iter),$(word $(jter),$2)),$(jter))\
  )\
)\
)

Best regards,
John D.