mk/*: improve documentation for "make help"

4 files changed, 33 insertions, 8 deletions

diff --git a/mk/alternatives.mk b/mk/alternatives.mk
index baf3fe91350..9e4d8da0931 100644
--- a/mk/alternatives.mk
+++ b/mk/alternatives.mk
@@ -1,4 +1,4 @@
-# $NetBSD: alternatives.mk,v 1.12 2015/11/25 13:05:47 jperkin Exp $
+# $NetBSD: alternatives.mk,v 1.13 2018/05/16 21:23:02 rillig Exp $
 #
 # This Makefile fragment handles the alternatives system, registering a
 # package in the database.
@@ -16,15 +16,23 @@
 #	Default value: The name of the ALTERNATIVES file in the package
 #	directory, if it exists. Otherwise, nothing.
 #
-#	Each line of the alternatives file contains two filenames, first
-#	the wrapper and then the alternative provided by the package.
+#	Each line of the alternatives file contains two filenames:
+#
+#		wrapper   alternative
+#
+#	The wrapper is the command that is run by the user.
+#	The alternative is the implementation of that command that is
+#	provided by the package.
 #	Both paths are relative to PREFIX.
+#	The paths may use placeholders of the form @VARNAME@, which are
+#	replaced with the actual values as per FILES_SUBST.
 #
 # Variables defined by this file:
 #
 # PKG_ALTERNATIVES
 #	The path to the pkg_alternatives command.
 #
+# Keywords: alternatives
 
 .if !defined(ALTERNATIVES_MK)
 ALTERNATIVES_MK=	# defined
diff --git a/mk/build/build.mk b/mk/build/build.mk
index 4fc61febebe..560cbb66cf8 100644
--- a/mk/build/build.mk
+++ b/mk/build/build.mk
@@ -1,4 +1,4 @@
-# $NetBSD: build.mk,v 1.22 2017/06/01 02:15:10 jlam Exp $
+# $NetBSD: build.mk,v 1.23 2018/05/16 21:23:02 rillig Exp $
 #
 # This file defines what happens in the build phase, excluding the
 # self-test, which is defined in test.mk.
@@ -180,6 +180,21 @@ post-build:
 	@${DO_NADA}
 .endif
 
+# build-env:
+#	Starts an interactive shell in WRKSRC.
+#
+#	This is only used during development and testing of a package
+#	to work in the same environment as the actual build.
+#
+# User-settable variables:
+#
+# BUILD_ENV_SHELL
+#	The shell to start.
+#
+#	Default: ${SH}
+#
+# Keywords: debug build
+
 BUILD_ENV_SHELL?=	${SH}
 .if defined(_PKGSRC_BARRIER)
 build-env: .PHONY configure
diff --git a/mk/install/bin-install.mk b/mk/install/bin-install.mk
index 05eda1e6b9a..1feb87b3ceb 100644
--- a/mk/install/bin-install.mk
+++ b/mk/install/bin-install.mk
@@ -1,4 +1,4 @@
-# $NetBSD: bin-install.mk,v 1.26 2017/08/19 00:30:19 jlam Exp $
+# $NetBSD: bin-install.mk,v 1.27 2018/05/16 21:23:02 rillig Exp $
 #
 
 # This file provides the following targets:
@@ -27,8 +27,9 @@
 # XXX: This file contains implementation details from the "pkg" format,
 # for example the All/ directory and the @cwd.
 
-# List of sites carrying binary pkgs. Variables "rel" and "arch" are
-# replaced with OS release ("1.5", ...) and architecture ("mipsel", ...)
+# List of sites carrying binary packages. Shell Variables "rel" and
+# "arch" are replaced with OS release ("1.5", ...) and architecture
+# ("mipsel", ...).
 .if ${OPSYS} == "NetBSD"
 BINPKG_SITES?= \
 	http://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/$${arch}/$${rel} \
diff --git a/mk/misc/can-be-built-here.mk b/mk/misc/can-be-built-here.mk
index ba23f0be8bb..93852febf9b 100644
--- a/mk/misc/can-be-built-here.mk
+++ b/mk/misc/can-be-built-here.mk
@@ -1,4 +1,4 @@
-# $NetBSD: can-be-built-here.mk,v 1.8 2015/01/01 06:06:06 dholland Exp $
+# $NetBSD: can-be-built-here.mk,v 1.9 2018/05/16 21:23:02 rillig Exp $
 #
 # This file checks whether a package can be built in the current pkgsrc
 # environment. It checks the following variables:
@@ -20,6 +20,7 @@
 #	XXX: It's weird to have three negations in such a short variable
 #	name.
 #
+# Keywords: compiler broken only platform
 
 _CBBH_CHECKS=		# none, but see below.