[Boost-build] invalid/outdated comments & code in generators.jam

From: Jurko Gospodnetiæ (jurko.gospodnetic_at_[hidden])
Date: 2008-04-30 15:38:30

   Hi all.

   generators.jam module seems to have traces of comments and 
implementation related to special handling or some multiple target 
generation cases which seems to have been implemented at one time but 
then incompletely removed in revision 29361 (committed by Volodya).

   I'm attaching a patch (description: Removed some old corpse comments 
and debugging output code related to functionality long removed in 
revision 29361.) based on revision 44943 and if no one objects will 
commit it.

   Volodya, could you look at the following paragraph in its main module 
comment and say if it is OK to remove it? Or should it be transformed 
into something else? It seems outdated as the construct() rule no longer 
takes any such parameter.
-------------
   That early conversion is not always desirable. Suppose a generator 
got a source of type Y and must consume one target of type X_1 and one 
target of type X_2. When converting Y to X_1 extra target of type Y_2 is 
created. We should not try to convert it to type X_1, because if we do 
so, the generator will get two targets of type X_1, and will be at loss 
as to which one to use. Because of that, the 'construct' rule has a 
parameter, telling if multiple targets can be returned. If the parameter 
is false, conversion of extra targets is not performed.
-------------

   Also, could you look at the paragraph above it which says '(Later 
I'll document the rationale for trying extra target conversion at that 
point)'? I'd fix if but I am still not at home with how this all 
works... :-)

   generator.run() rule has the following debug output line in it:

         generators.dout [ indent ] "  multiple:" $(mutliple) ;

   which can never do anything useful both because of the typo in the 
variable name and because no variable with even a similar name exists in 
this module.

   construct() rule does not take any 'multiple' parameter but its 
comment states:
-------------
   If 'multiple' is true, the rule is allowed to return several targets 
of 'target-type'.
-------------

   Best regards,
     Jurko Gospodnetiæ

Index: tools/build/v2/build/generators.jam
===================================================================
--- tools/build/v2/build/generators.jam	(revision 44943)
+++ tools/build/v2/build/generators.jam	(working copy)
@@ -36,15 +36,6 @@
 #  attempts that as early as possible. Specifically, this is done after invoking
 #  each generator. (Later I'll document the rationale for trying extra target
 #  conversion at that point).
-#
-#  That early conversion is not always desirable. Suppose a generator got a
-#  source of type Y and must consume one target of type X_1 and one target of
-#  type X_2. When converting Y to X_1 extra target of type Y_2 is created. We
-#  should not try to convert it to type X_1, because if we do so, the generator
-#  will get two targets of type X_1, and will be at loss as to which one to use.
-#  Because of that, the 'construct' rule has a parameter, telling if multiple
-#  targets can be returned. If the parameter is false, conversion of extra
-#  targets is not performed.
 
 import "class" : new ;
 import errors ;
@@ -293,7 +284,6 @@
             )
     {
         generators.dout [ indent ] "  ** generator" $(self.id) ;
-        generators.dout [ indent ] "  multiple:" $(mutliple) ;
         generators.dout [ indent ] "  composing:" $(self.composing) ;
 
         if ! $(self.composing) && $(sources[2]) && $(self.source-types[2])
@@ -1163,8 +1153,7 @@
 
 # Attempts to create a target of 'target-type' with 'properties' from 'sources'.
 # The 'sources' are treated as a collection of *possible* ingridients -- i.e. it
-# is not required to consume them all. If 'multiple' is true, the rule is
-# allowed to return several targets of 'target-type'.
+# is not required to consume them all.
 #
 # Returns a list of targets. When this invocation is first instance of
 # 'construct' in stack, returns only targets of requested 'target-type',