From a858c2dc3cf63b8d2f60abde4fb143329dca281c Mon Sep 17 00:00:00 2001
From: Peter Dimov <pdimov@pdimov.com>
Date: Fri, 12 Oct 2018 21:32:12 +0300
Subject: [PATCH] Add comments explaining the stage/install targets in
 build/Jamfile

---
 build/Jamfile | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/build/Jamfile b/build/Jamfile
index c170b1f7..34f99dde 100644
--- a/build/Jamfile
+++ b/build/Jamfile
@@ -133,12 +133,24 @@ lib boost_numpy
         <python-debugging>on:<define>BOOST_DEBUG_PYTHON
     ;
 
+# boost-install creates `stage` and `install` targets
+#
+# `stage` stages (builds and copies into `stage/lib`) the given libraries
+#   `boost_python` and `boost_numpy` and their dependencies and is similar
+#   to issuing `b2 --with-python stage` from top level
+#
+# `install` installs the two libraries and their dependencies and is similar
+#   to issuing `b2 --with-python install` from top level
+
 boost-install boost_python boost_numpy ;
 
 }
 else
 {
-# Python not configured
+
+# When Python isn't configured, the above `boost-install` is not executed,
+# so we create empty `stage` and `install` targets that do nothing but issue
+# a warning message unless `--without-python` is given
 
 alias stage : config-warning ;
 explicit stage ;