[Boost-commit] svn:boost r44941 - trunk/tools/build/v2/build

From: jurko.gospodnetic_at_[hidden]
Date: 2008-04-30 15:24:04

Author: jurko
Date: 2008-04-30 15:24:04 EDT (Wed, 30 Apr 2008)
New Revision: 44941
URL: http://svn.boost.org/trac/boost/changeset/44941

Log:
Comment cleanup - both stylistic & typo corrections.
Text files modified: 
   trunk/tools/build/v2/build/generators.jam |   146 ++++++++++++++++++--------------------- 
   1 files changed, 69 insertions(+), 77 deletions(-)

Modified: trunk/tools/build/v2/build/generators.jam
==============================================================================
--- trunk/tools/build/v2/build/generators.jam	(original)
+++ trunk/tools/build/v2/build/generators.jam	2008-04-30 15:24:04 EDT (Wed, 30 Apr 2008)
@@ -93,8 +93,8 @@
 
 
 # Takes a vector of 'virtual-target' instances and makes a normalized
-# representation, which is the same for given set of targets,
-# regardless of their order.
+# representation, which is the same for given set of targets, regardless of
+# their order.
 #
 rule normalize-target-list ( targets )
 {
@@ -183,19 +183,19 @@
         return $(self.source-types) ;
     }
 
-    # Returns the list of target types that this generator produces.
-    # It is assumed to be always the same -- i.e. it cannot change depending
-    # list of sources.
+    # Returns the list of target types that this generator produces. It is
+    # assumed to be always the same -- i.e. it cannot change depending list of
+    # sources.
     #
     rule target-types ( )
     {
         return $(self.target-types) ;
     }
 
-    # Returns the required properties for this generator. Properties
-    # in returned set must be present in build properties if this
-    # generator is to be used. If result has grist-only element,
-    # that build properties must include some value of that feature.
+    # Returns the required properties for this generator. Properties in returned
+    # set must be present in build properties if this generator is to be used.
+    # If result has grist-only element, that build properties must include some
+    # value of that feature.
     # XXX: remove this method?
     #
     rule requirements ( )
@@ -208,10 +208,9 @@
     #
     rule match-rank ( property-set-to-match )
     {
-        # See if generator's requirements are satisfied by
-        # 'properties'.  Treat a feature name in requirements
-        # (i.e. grist-only element), as matching any value of the
-        # feature.
+        # See if generator's requirements are satisfied by 'properties'. Treat a
+        # feature name in requirements (i.e. grist-only element), as matching
+        # any value of the feature.
         local all-requirements = [ requirements ] ;
 
         local property-requirements feature-requirements ;
@@ -239,9 +238,9 @@
         }
     }
 
-    # Returns another generator which differers from $(self) in
-    # - id
-    # - value to <toolset> feature in properties
+    # Returns another generator which differs from $(self) in
+    #   - id
+    #   - value to <toolset> feature in properties
     #
     rule clone ( new-id : new-toolset-properties + )
     {
@@ -287,8 +286,8 @@
     # run indicates that the generator was unable to create the target.
     #
     rule run ( project  # Project for which the targets are generated
-               name ?   # Determines the name of 'name' attribute for
-                        # all generated targets. See 'generated-targets' method.
+               name ?   # Determines the name of 'name' attribute for all
+                        # generated targets. See 'generated-targets' method.
                : property-set # Desired properties for generated targets.
                : sources +  # Source targets.
             )
@@ -360,15 +359,16 @@
     rule construct-result (
         consumed + # Already prepared list of consumable targets
                    # If generator requires several source files will contain
-                   # exactly len $(self.source-types) targets with matching types
-                   # Otherwise, might contain several targets with the type of
-                   # $(self.source-types[1])
+                   # exactly len $(self.source-types) targets with matching
+                   # types. Otherwise, might contain several targets with the
+                   # type of $(self.source-types[1]).
         : project name ?
         : property-set  # Properties to be used for all actions create here.
     )
     {
         local result ;
-        # If this is 1->1 transformation, apply it to all consumed targets in order.
+        # If this is 1->1 transformation, apply it to all consumed targets in
+        # order.
         if ! $(self.source-types[2]) && ! $(self.composing)
         {
             for local r in $(consumed)
@@ -391,15 +391,14 @@
     #
     rule determine-output-name ( sources + )
     {
-        # The simple case if when a name
-        # of source has single dot. Then, we take the part before
-        # dot. Several dots can be caused by:
-        # - Using source file like a.host.cpp
-        # - A type which suffix has a dot. Say, we can
-        #   type 'host_cpp' with extension 'host.cpp'.
-        # In the first case, we want to take the part till the last
-        # dot. In the second case -- no sure, but for now take
-        # the part till the last dot too.
+        # The simple case if when a name of source has single dot. Then, we take
+        # the part before dot. Several dots can be caused by:
+        #   - Using source file like a.host.cpp
+        #   - A type which suffix has a dot. Say, we can type 'host_cpp' with
+        #     extension 'host.cpp'.
+        # In the first case, we want to take the part up to the last dot. In the
+        # second case -- no sure, but for now take the part up to the last dot
+        # too.
         name = [ utility.basename [ $(sources[1]).name ] ] ;
 
         for local s in $(sources[2])
@@ -467,9 +466,9 @@
         return [ sequence.transform virtual-target.register : $(targets) ] ;
     }
 
-    # Attempts to convert 'source' to the types that this generator can
-    # handle. The intention is to produce the set of targets can should be
-    # used when generator is run.
+    # Attempts to convert 'source' to the types that this generator can handle.
+    # The intention is to produce the set of targets can should be used when
+    # generator is run.
     #
     rule convert-to-consumable-types ( project name ? :
         property-set : sources +
@@ -481,16 +480,16 @@
                        # cannot be consumed
     )
     {
-        # We're likely to be passed 'consumed' and 'bypassed'
-        # var names. Use "_" to avoid name conflicts.
+        # We're likely to be passed 'consumed' and 'bypassed' var names. Use "_"
+        # to avoid name conflicts.
         local _consumed ;
         local _bypassed ;
         local missing-types ;
 
         if $(sources[2])
         {
-            # Don't know how to handle several sources yet. Just try
-            # to pass the request to other generator
+            # Don't know how to handle several sources yet. Just try to pass the
+            # request to other generator
             missing-types = $(self.source-types) ;
         }
         else
@@ -498,18 +497,17 @@
             consume-directly $(sources) : _consumed : missing-types ;
         }
 
-        # No need to search for transformation if
-        # some source type has consumed source and
-        # no more source types are needed.
+        # No need to search for transformation if some source type has consumed
+        # source and no more source types are needed.
         if $(only-one) && $(_consumed)
         {
             missing-types = ;
         }
 
-        #TODO: we should check that only one source type
-        #if create of 'only-one' is true.
-        # TODO: consider if consuned/bypassed separation should
-        # be done by 'construct-types'.
+        # TODO: we should check that only one source type if create of
+        # 'only-one' is true.
+        # TODO: consider if consumed/bypassed separation should be done by
+        # 'construct-types'.
 
         if $(missing-types)
         {
@@ -538,15 +536,14 @@
         _consumed = [ sequence.unique $(_consumed) ] ;
         _bypassed = [ sequence.unique $(_bypassed) ] ;
 
-        # remove elements of '_bypassed' that are in '_consumed'
+        # Remove elements of '_bypassed' that are in '_consumed'.
 
-        # Suppose the target type of current generator, X is produced from
-        # X_1 and X_2, which are produced from Y by one generator.
-        # When creating X_1 from Y, X_2 will be added to 'bypassed'
-        # Likewise, when creating X_2 from Y, X_1 will be added to 'bypassed'
-        # But they are also in 'consumed'. We have to remove them from
-        # bypassed, so that generators up the call stack don't try to convert
-        # them.
+        # Suppose the target type of current generator, X is produced from X_1
+        # and X_2, which are produced from Y by one generator. When creating X_1
+        # from Y, X_2 will be added to 'bypassed'. Likewise, when creating X_2
+        # from Y, X_1 will be added to 'bypassed', but they are also in
+        # 'consumed'. We have to remove them from bypassed, so that generators
+        # up the call stack don't try to convert them.
 
         # In this particular case, X_1 instance in 'consumed' and X_1 instance
         # in 'bypassed' will be the same: because they have the same source and
@@ -555,7 +552,6 @@
 
         _bypassed = [ set.difference $(_bypassed) : $(_consumed) ] ;
 
-
         $(consumed-var) += $(_consumed) ;
         $(bypassed-var) += $(_bypassed) ;
     }
@@ -565,8 +561,8 @@
     rule convert-multiple-sources-to-consumable-types
       ( project : property-set : sources * : consumed-var bypassed-var )
     {
-        # We process each source one-by-one, trying to convert it to
-        # a usable type.
+        # We process each source one-by-one, trying to convert it to a usable
+        # type.
         for local source in $(sources)
         {
             local _c ;
@@ -587,7 +583,7 @@
     {
         local real-source-type = [ $(source).type ] ;
 
-        # If there are no source types, we can consume anything
+        # If there are no source types, we can consume anything.
         local source-types = $(self.source-types) ;
         source-types ?= $(real-source-type) ;
 
@@ -606,8 +602,8 @@
         }
     }
 
-    # Returns the class to be used to actions. Default implementation
-    # returns "action".
+    # Returns the class to be used to actions. Default implementation returns
+    # "action".
     #
     rule action-class ( )
     {
@@ -625,10 +621,9 @@
 {
     .generators += $(g) ;
 
-    # A generator can produce several targets of the
-    # same type. We want unique occurence of that generator
-    # in .generators.$(t) in that case, otherwise, it will
-    # be tried twice and we'll get false ambiguity.
+    # A generator can produce several targets of the same type. We want unique
+    # occurence of that generator in .generators.$(t) in that case, otherwise,
+    # it will be tried twice and we'll get false ambiguity.
     for local t in [ sequence.unique [ $(g).target-types ] ]
     {
         .generators.$(t) += $(g) ;
@@ -636,20 +631,17 @@
 
     # Update the set of generators for toolset
 
-    # TODO: should we check that generator with this id
-    # is not already registered. For example, the fop.jam
-    # module intentionally declared two generators with the
-    # same id, so such check will break it.
+    # TODO: should we check that generator with this id is not already
+    # registered. For example, the fop.jam module intentionally declared two
+    # generators with the same id, so such check will break it.
     local id = [ $(g).id ] ;
 
-    # Some generators have multiple periods in their name, so the
-    # normal $(id:S=) won't generate the right toolset name.
-    # e.g. if id = gcc.compile.c++, then
-    # .generators-for-toolset.$(id:S=) will append to
-    # .generators-for-toolset.gcc.compile, which is a separate
-    # value from .generators-for-toolset.gcc. Correcting this
-    # makes generator inheritance work properly.
-    # See also inherit-generators in module toolset
+    # Some generators have multiple periods in their name, so the normal
+    # $(id:S=) won't generate the right toolset name. E.g. if id =
+    # = gcc.compile.c++, then .generators-for-toolset.$(id:S=) will append to
+    # .generators-for-toolset.gcc.compile, which is a separate value from
+    # .generators-for-toolset.gcc. Correcting this makes generator inheritance
+    # work properly. See also inherit-generators in the toolset module.
     local base = $(id) ;
     while $(base:S)
     {
@@ -729,8 +721,8 @@
     # 't' is the list of types which have not yet been processed.
     while $(t)
     {
-        # Find all generators for current type.
-        # Unlike 'find-viable-generators' we don't care about property-set.
+        # Find all generators for current type. Unlike 'find-viable-generators'
+        # we don't care about property-set.
         local generators = $(.generators.$(t[1])) ;
         t = $(t[2-]) ;