build: add comments to makefiles

Add comments to build system makefile functions and variables to help
developers in understanding build system internals and ease the
development process.

This patch adds some documentation examples with proposed doxygen-like
syntax. Hopefully, this would start the discussion and result in
generation of the makefile documentation guidelines.

Signed-off-by: Sergey Matsievskiy <matsievskiysv@gmail.com>
Link: https://github.com/openwrt/openwrt/pull/16888
Signed-off-by: Christian Marangi <ansuelsmth@gmail.com>

include/image.mk

@@ -21,6 +21,11 @@ include $(INCLUDE_DIR)/rootfs.mk
 override MAKE:=$(_SINGLE)$(SUBMAKE)
 override NO_TRACE_MAKE:=$(_SINGLE)$(NO_TRACE_MAKE)
 
+##@
+# @brief Convert size with unit postfix to unitless expression in bytes.
+#
+# @param 1: Size with unit. Possible unit postfix are `g`, `m`, `k`.
+##
 exp_units = $(subst k, * 1024,$(subst m, * 1024k,$(subst g, * 1024m,$(1))))
 
 target_params = $(subst +,$(space),$*)
@@ -111,6 +116,12 @@ endef
 
 PROFILE_SANITIZED := $(call tolower,$(subst DEVICE_,,$(subst $(space),-,$(PROFILE))))
 
+##@
+# @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),\
@@ -118,12 +129,24 @@ $(foreach data, \
 	$(call $(2),$(strip $(subst ^,$(space),$(data)))))
 endef
 
+##@
+# @brief Call build function with arguments.
+#
+# @param 1: Function to call. Function name is prepended with `Build/`.
+# @param 2...: Function arguments.
+##
 define build_cmd
 $(if $(Build/$(word 1,$(1))),,$(error Missing Build/$(word 1,$(1))))
 $(call Build/$(word 1,$(1)),$(wordlist 2,$(words $(1)),$(1)))
 
 endef
 
+##@
+# @brief Call build functions from the list.
+#
+# @param 1: List of build functions with arguments, separated by `|`.
+#           First word in each group is a build command without `Build/` prefix.
+##
 define concat_cmd
 $(call split_args,$(1),build_cmd)
 endef
@@ -163,6 +186,12 @@ DTC_WARN_FLAGS := \
 DTC_FLAGS += $(DTC_WARN_FLAGS)
 DTCO_FLAGS += $(DTC_WARN_FLAGS)
 
+##@
+# @brief Pad file to specified size.
+#
+# @param 1: File.
+# @param 2: Padding.
+##
 define Image/pad-to
 	dd if=$(1) of=$(1).new bs=$(2) conv=sync
 	mv $(1).new $(1)
@@ -403,26 +432,53 @@ define Device/InitProfile
   DEVICE_DESCRIPTION = Build firmware images for $$(DEVICE_TITLE)
 endef
 
+##@
+# @brief Image configuration variables.
+#
+# @param 1: Device name.
+##
 define Device/Init
+  ##@ Device name.
   DEVICE_NAME := $(1)
+  ##@ Commands to build kernel.
+  # Commands with arguments are separated by `|`.
+  ##
   KERNEL:=
+  ##@ Commands to build initramfs.
+  # Commands with arguments are separated by `|`.
+  ##
   KERNEL_INITRAMFS = $$(KERNEL)
+  ##@ Kernel command line.
   CMDLINE:=
 
+  ##@ Images to build.
   IMAGES :=
+  ##@ Artifacts to build.
   ARTIFACTS :=
+  ##@ Device image prefix.
   DEVICE_IMG_PREFIX := $(IMG_PREFIX)-$(1)
+  ##@ Device image name.
   DEVICE_IMG_NAME = $$(DEVICE_IMG_PREFIX)-$$(1)-$$(2)
+  ##@ Factory image name.
   FACTORY_IMG_NAME :=
+  ##@ Maximum image size. Optional.
   IMAGE_SIZE :=
+  ##@ Maximum image size. Optional.
   NAND_SIZE :=
+  ##@ Kernel image prefix.
   KERNEL_PREFIX = $$(DEVICE_IMG_PREFIX)
+  ##@ Kernel image suffix.
   KERNEL_SUFFIX := -kernel.bin
+  ##@ Initramfs image suffix.
   KERNEL_INITRAMFS_SUFFIX = $$(KERNEL_SUFFIX)
+  ##@ Kernel image name.
   KERNEL_IMAGE = $$(KERNEL_PREFIX)$$(KERNEL_SUFFIX)
+  ##@ Initramfs image prefix.
   KERNEL_INITRAMFS_PREFIX = $$(DEVICE_IMG_PREFIX)-initramfs
   KERNEL_INITRAMFS_IMAGE = $$(KERNEL_INITRAMFS_PREFIX)$$(KERNEL_INITRAMFS_SUFFIX)
+  ##@ Initramfs image name.
   KERNEL_INITRAMFS_NAME = $$(KERNEL_NAME)-initramfs
+  ##@ Kernel install flag.
   KERNEL_INSTALL :=
   KERNEL_NAME := vmlinux
   KERNEL_DEPENDS :=

include/target.mk

@@ -7,10 +7,17 @@ ifneq ($(__target_inc),1)
 __target_inc=1
 
 
-# default device type
+##@
+# @brief Default device type ( basic | nas | router ).
+##
 DEVICE_TYPE?=router
 
-# Default packages - the really basic set
+##@
+# @brief Default packages.
+#
+# The really basic set. Additional packages are added based on @DEVICE_TYPE and
+# @CONFIG_* values.
+##
 DEFAULT_PACKAGES:=\
 	base-files \
 	ca-bundle \
@@ -27,15 +34,21 @@ DEFAULT_PACKAGES:=\
 	urandom-seed \
 	urngd
 
-# For the basic set
+##@
+# @brief Default packages for @DEVICE_TYPE basic.
+##
 DEFAULT_PACKAGES.basic:=
-# For nas targets
+##@
+# @brief Default packages for @DEVICE_TYPE nas.
+##
 DEFAULT_PACKAGES.nas:=\
 	block-mount \
 	fdisk \
 	lsblk \
 	mdadm
-# For router targets
+##@
+# @brief Default packages for @DEVICE_TYPE router.
+##
 DEFAULT_PACKAGES.router:=\
 	dnsmasq \
 	firewall4 \
@@ -85,7 +98,18 @@ endif
 # Add device specific packages (here below to allow device type set from subtarget)
 DEFAULT_PACKAGES += $(DEFAULT_PACKAGES.$(DEVICE_TYPE))
 
+##@
+# @brief Filter out packages, prepended with `-`.
+#
+# @param 1: Package list.
+##
 filter_packages = $(filter-out -% $(patsubst -%,%,$(filter -%,$(1))),$(1))
+
+##@
+# @brief Append extra package dependencies.
+#
+# @param 1: Package list.
+##
 extra_packages = $(if $(filter wpad wpad-% nas,$(1)),iwinfo)
 
 define ProfileDefault

rules.mk

@@ -20,6 +20,11 @@ endif
 export TMP_DIR:=$(TOPDIR)/tmp
 export TMPDIR:=$(TMP_DIR)
 
+##@
+# @brief Strip quotes `"` and pounds `#` from string.
+#
+# @param 1: String.
+##
 qstrip=$(strip $(subst ",,$(1)))
 #"))
 
@@ -27,8 +32,23 @@ empty:=
 space:= $(empty) $(empty)
 comma:=,
 pound:=\#
+##@
+# @brief Merge strings by removing spaces.
+#
+# @param 1: String.
+##
 merge=$(subst $(space),,$(1))
+##@
+# @brief Get hash sum of variable list.
+#
+# @param 1: List of variable names.
+##
 confvar=$(shell echo '$(foreach v,$(1),$(v)=$(subst ','\'',$($(v))))' | $(MKHASH) md5)
+##@
+# @brief Strip last extension from file name.
+#
+# @param 1: File name.
+##
 strip_last=$(patsubst %.$(lastword $(subst .,$(space),$(1))),%,$(1))
 
 paren_left = (
@@ -51,9 +71,18 @@ __tr_head = $(subst $(paren_left)subst,$(paren_left)subst$(space),$(__tr_head_st
 __tr_tail = $(subst $(space),,$(foreach cv,$(1),$(paren_right)))
 __tr_template = $(__tr_head)$$(1)$(__tr_tail)
 
+##@
+# @brief Convert string characters to upper.
+##
 $(eval toupper = $(call __tr_template,$(chars_lower),$(chars_upper)))
+##@
+# @brief Convert string characters to lower.
+##
 $(eval tolower = $(call __tr_template,$(chars_upper),$(chars_lower)))
 
+##@
+# @brief Abbreviate version. Truncate to 8 characters.
+##
 version_abbrev = $(if $(if $(CHECK),,$(DUMP)),$(1),$(shell printf '%.8s' $(1)))
 
 _SINGLE=export MAKEFLAGS=$(space);
@@ -102,6 +131,13 @@ endif
 
 DEFAULT_SUBDIR_TARGETS:=clean download prepare compile update refresh prereq dist distcheck configure check check-depends
 
+##@
+# @brief Create default targets.
+#
+# Targets are created from @DEFAULT_SUBDIR_TARGETS and input argument lists.
+#
+# @param 1: Additional targets list.
+##
 define DefaultTargets
 $(foreach t,$(DEFAULT_SUBDIR_TARGETS) $(1),
   .$(t):
@@ -371,16 +407,28 @@ export BISON_PKGDATADIR:=$(STAGING_DIR_HOST)/share/bison
 export HOST_GNULIB_SRCDIR:=$(STAGING_DIR_HOST)/share/gnulib
 export M4:=$(STAGING_DIR_HOST)/bin/m4
 
+##@
+# @brief Slugify variable name and prepend suffix.
+##
 define shvar
 V_$(subst .,_,$(subst -,_,$(subst /,_,$(1))))
 endef
 
+##@
+# @brief Create and export variable, set to function result.
+#
+# @param 1: Function name. Used as variable name, prepended with `V_`.
+##
 define shexport
 export $(call shvar,$(1))=$$(call $(1))
 endef
 
+##@
+# @brief Support 64 bit tine in C code.
+#
 # Test support for 64-bit time with C code from largefile.m4 provided by GNU Gnulib
-# the value is 'y' when successful and '' otherwise
+# the value is `y` when successful and `` otherwise
+##
 define YEAR_2038
 $(shell \
   mkdir -p $(TMP_DIR); \
@@ -392,9 +440,12 @@ $(shell \
 )
 endef
 
-# Execute commands under flock
+##@
-# $(1) => The shell expression.
+# @brief Execute commands under flock
-# $(2) => The lock name. If not given, the global lock will be used.
+#
+# @param 1: The shell expression.
+# @param 2: The lock name. If not given, the global lock will be used.
+##
 ifneq ($(wildcard $(STAGING_DIR_HOST)/bin/flock),)
   define locked
 	SHELL= \
@@ -406,10 +457,14 @@ else
   locked=$(1)
 endif
 
-# Recursively copy paths into another directory, purge dangling
+
+##@
+# @brief Recursively copy paths into another directory, purge dangling
 # symlinks before.
-# $(1) => File glob expression
+#
-# $(2) => Destination directory
+# @param 1: File glob expression.
+# @param 1: Destination directory.
+##
 define file_copy
 	for src_dir in $(sort $(foreach d,$(wildcard $(1)),$(dir $(d)))); do \
 		( cd $$src_dir; find -type f -or -type d ) | \
@@ -424,19 +479,30 @@ define file_copy
 	$(CP) $(1) $(2)
 endef
 
-# Calculate sha256sum of any plain file within a given directory
+##@
-# $(1) => Input directory
+# @brief Calculate sha256sum of any plain file within a given directory.
-# $(2) => If set, recurse into subdirectories
+#
+# @param 1: Input directory.
+# @param 2: If set, recurse into subdirectories.
+##
 define sha256sums
 	(cd $(1); find . $(if $(2),,-maxdepth 1) -type f -not -name 'sha256sums' -printf "%P\n" | sort | \
 		xargs -r $(MKHASH) -n sha256 | sed -ne 's!^\(.*\) \(.*\)$$!\1 *\2!p' > sha256sums)
 endef
 
-# file extension
+##@
+# @brief Retrieve file extension.
+#
+# @param 1: File name.
+##
 ext=$(word $(words $(subst ., ,$(1))),$(subst ., ,$(1)))
 
-# Count Git commits of a package
+##@
-# $(1) => if non-empty: count commits since last ": [uU]pdate to " or ": [bB]ump to " in commit message
+# @brief Count Git commits of a package.
+#
+# @param 1: if non-empty: count commits since last ": [uU]pdate to "
+#           or ": [bB]ump to " in commit message.
+##
 define commitcount
 $(shell \
   if git log -1 >/dev/null 2>/dev/null; then \
@@ -458,6 +524,11 @@ $(shell \
 )
 endef
 
+##@
+# @brief Get ABI version string, stripping `-`, `_` and `.`.
+#
+# @param 1: Version string.
+##
 abi_version_str = $(subst -,,$(subst _,,$(subst .,,$(1))))
 
 COMMITCOUNT = $(if $(DUMP),0,$(call commitcount))