Build system inline documentation

Talk about Documentation
1

Hello!

I'm studying the OpenWRT build system to add a new target. While at it, I could add Doxygen like comments to the makefiles.
If such a contribution is welcome, what should be the preferred documentation syntax?

1 Like
2

Maybe something like

##@
# @brief Call function for each group of arguments.
#
# @param 1: List of lists of arguments. Lists are separated by `|`.
# @param 2: Function to call for list of arguments.
##
define split_args
$(foreach data, \
	$(subst |,$(space),\
		$(subst $(space),^,$(1))), \
	$(call $(2),$(strip $(subst ^,$(space),$(data)))))
endef
3

I also think this is a good idea.
It took me a whole week to understand the Makefile for OpenWrt...

1 Like
4

To those of you who understand the build system, could you please write a guide for everyone else interested? Thanks!

Brief comments in code don't paint the big picture.

5

Brief comments in code don't paint the big picture.

True, but it's better than nothing:)

The testing commit https://github.com/openwrt/openwrt/pull/16888 got merged; the Doxygen like syntax from the message above may be used for documentation. If anyone would like to participate in this task, patches are welcome.

1 Like
6

How can I generate documentation from these .mk files using doxygen?

7

AFAIK, there're no make documentation generators available.

8

I'm slowly adding more comments. The progress may be tracked at github (branch is subject to squashing and force pushes).

2 Likes
9

I suppose a sed or awk script could extract these comments, compile something useful out of them and print them out. Not a bad idea IMO.

Also, great job @matsievskiysv :clap: