From 0ef38e6dbee661921d9fad371734e7bfa5160fae Mon Sep 17 00:00:00 2001
From: Nicolas Boulenguez <nicolas@debian.org>
Date: Sun, 13 Feb 2022 13:41:26 +0100
Subject: [PATCH 09/10] scripts/mk: improve details in documentation

architecture.mk: give more details
Mention default.mk as an alternative in included scripts.
Improve consistency accross Makefile snippets.
---
 scripts/mk/architecture.mk | 15 ++++++++++++---
 scripts/mk/buildflags.mk   |  5 +++--
 scripts/mk/buildopts.mk    |  7 +++----
 scripts/mk/buildtools.mk   |  5 +++--
 scripts/mk/pkg-info.mk     |  5 +++--
 scripts/mk/vendor.mk       |  5 +++--
 6 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/scripts/mk/architecture.mk b/scripts/mk/architecture.mk
index 174c5b638..a7e31cf16 100644
--- a/scripts/mk/architecture.mk
+++ b/scripts/mk/architecture.mk
@@ -1,6 +1,15 @@
-# This Makefile fragment (since dpkg 1.16.1) defines all the DEB_HOST_* and
-# DEB_BUILD_* variables that dpkg-architecture can return. Existing values
-# of those variables are preserved as per policy.
+# debian/rules helper defining the dpkg-architecture(1) variables.
+# (since dpkg 1.16.1)
+# Include this (or default.mk) if using DEB_{HOST,BUILD,TARGET}_*.
+#
+# These variables are usually computed by dpkg-buildpackage and simply
+# inherited by debian/rules, but need a definition when debian/rules
+# is invoked directly.
+#
+# Each variable may be overridden by the end user (on the debian/rules
+# command line) or by the maintainer (within debian/rules).
+#
+# All values are unconditionally exported.
 
 ifndef dpkg_architecture.mk_included
 dpkg_architecture.mk_included :=
diff --git a/scripts/mk/buildflags.mk b/scripts/mk/buildflags.mk
index f0d32d78c..a186e88d8 100644
--- a/scripts/mk/buildflags.mk
+++ b/scripts/mk/buildflags.mk
@@ -1,5 +1,6 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following host
-# variables:
+# debian/rules helper defining the dpkg-buildflags(1) variables.
+# Include this (or default.mk) if using
+# these host variables (since dpkg 1.16.1):
 #
 #   ASFLAGS: flags for the host assembler (since 1.21.0).
 #   CFLAGS: flags for the host C compiler.
diff --git a/scripts/mk/buildopts.mk b/scripts/mk/buildopts.mk
index 58e2bca67..12a76262c 100644
--- a/scripts/mk/buildopts.mk
+++ b/scripts/mk/buildopts.mk
@@ -1,7 +1,6 @@
-# This Makefile fragment (since dpkg 1.20.1) parses option arguments from
-# DEB_BUILD_OPTIONS, and exposes these as variables.
-#
-# Defines the following variables:
+# debian/rules helper extracting some arguments from DEB_BUILD_OPTIONS.
+# (since dpkg 1.20.1)
+# Include this (or default.mk) if using:
 #
 #   DEB_BUILD_OPTION_PARALLEL: the argument for the parallel=N option.
 #     $(DEB_BUILD_OPTIONS)                "parallel=2"  "parallel="  ""
diff --git a/scripts/mk/buildtools.mk b/scripts/mk/buildtools.mk
index 9bb491ccc..95f8f8718 100644
--- a/scripts/mk/buildtools.mk
+++ b/scripts/mk/buildtools.mk
@@ -1,5 +1,6 @@
-# This Makefile fragment (since dpkg 1.19.0) defines the following variables
-# for host tools:
+# debian/rules helper defining some host and build tools
+# (since dpkg 1.19.0)
+# Include this if using:
 #
 #   AS: assembler (since dpkg 1.19.1).
 #   CPP: C preprocessor.
diff --git a/scripts/mk/pkg-info.mk b/scripts/mk/pkg-info.mk
index 5b3fd5d8f..d9a4b4466 100644
--- a/scripts/mk/pkg-info.mk
+++ b/scripts/mk/pkg-info.mk
@@ -1,5 +1,6 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following package
-# information variables:
+# debian/rules helper defining some dpkg-parsechangelog(1) variables.
+# (since 1.16.1)
+# Include this (or default.mk) if using:
 #
 #   DEB_SOURCE: source package name.
 #   DEB_VERSION: package's full version (epoch + upstream vers. + revision).
diff --git a/scripts/mk/vendor.mk b/scripts/mk/vendor.mk
index 2c4963cca..dc38aef36 100644
--- a/scripts/mk/vendor.mk
+++ b/scripts/mk/vendor.mk
@@ -1,5 +1,6 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following
-# vendor-related variables:
+# debian/rules helper defining some dpkg-vendor(1) variables.
+# (since dpkg 1.16.1)
+# Include this (or default.mk) if using:
 #
 #   DEB_VENDOR: output of «dpkg-vendor --query Vendor».
 #   DEB_PARENT_VENDOR: output of «dpkg-vendor --query Parent» (can be empty).
-- 
2.39.2

