From 9dda3d8f84aff9b85ce7c2a10dcc1773841eec17 Mon Sep 17 00:00:00 2001
From: Vladimir Prus <ghost@cs.msu.su>
Date: Thu, 22 May 2003 11:50:10 +0000
Subject: [PATCH] Add/clarify comments.

[SVN r18496]
---
 new/builtin.jam         | 8 ++++++--
 new/generators.jam      | 6 +++++-
 v2/build/generators.jam | 6 +++++-
 v2/tools/builtin.jam    | 8 ++++++--
 4 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/new/builtin.jam b/new/builtin.jam
index ee8adffba..f220cf493 100644
--- a/new/builtin.jam
+++ b/new/builtin.jam
@@ -621,10 +621,14 @@ rule link-action ( targets + : sources * : action-name : properties * )
 class link-action : action ;
 
 
-rule linking-generator ( id composing ? : source-types + : target-types + : 
+rule linking-generator ( id 
+    composing ? : # Specify if generator is composing. The generator will be
+                  # composing if non-empty string is passed, or parameter is
+                  # not given. To make generator non-composing, pass empty
+                  # string ("")
+    source-types + : target-types + : 
                          requirements * )
 {
-    # If composing is not specified, set it to true, which is "false" in Jam.
     composing ?= true ;
     generator.__init__ $(id) $(composing) : $(source-types) : $(target-types) :
                        $(requirements) ;
diff --git a/new/generators.jam b/new/generators.jam
index 594310830..4d4a66ab3 100644
--- a/new/generators.jam
+++ b/new/generators.jam
@@ -287,7 +287,11 @@ rule generator (
             multiple = ;
         }
         
-        # We don't run composing generators which are not given a name.
+        # We don't run composing generators if no name is specified. The reason
+        # is that composing generator combines several targets, which can have
+        # different names, and it cannot decide which name to give for produced
+        # target. Therefore, the name must be passed.
+        #
         # This in effect, means that composing generators are runnable only
         # at top-level of transofrmation graph, or if name is passed explicitly.
         # Thus, we dissallow composing generators in the middle. For example, the
diff --git a/v2/build/generators.jam b/v2/build/generators.jam
index 594310830..4d4a66ab3 100644
--- a/v2/build/generators.jam
+++ b/v2/build/generators.jam
@@ -287,7 +287,11 @@ rule generator (
             multiple = ;
         }
         
-        # We don't run composing generators which are not given a name.
+        # We don't run composing generators if no name is specified. The reason
+        # is that composing generator combines several targets, which can have
+        # different names, and it cannot decide which name to give for produced
+        # target. Therefore, the name must be passed.
+        #
         # This in effect, means that composing generators are runnable only
         # at top-level of transofrmation graph, or if name is passed explicitly.
         # Thus, we dissallow composing generators in the middle. For example, the
diff --git a/v2/tools/builtin.jam b/v2/tools/builtin.jam
index ee8adffba..f220cf493 100644
--- a/v2/tools/builtin.jam
+++ b/v2/tools/builtin.jam
@@ -621,10 +621,14 @@ rule link-action ( targets + : sources * : action-name : properties * )
 class link-action : action ;
 
 
-rule linking-generator ( id composing ? : source-types + : target-types + : 
+rule linking-generator ( id 
+    composing ? : # Specify if generator is composing. The generator will be
+                  # composing if non-empty string is passed, or parameter is
+                  # not given. To make generator non-composing, pass empty
+                  # string ("")
+    source-types + : target-types + : 
                          requirements * )
 {
-    # If composing is not specified, set it to true, which is "false" in Jam.
     composing ?= true ;
     generator.__init__ $(id) $(composing) : $(source-types) : $(target-types) :
                        $(requirements) ;