docs

docs/sphinx/featuremap_example.txt

@@ -1,35 +1,37 @@
-The feature system enables binding new behaviours to task generators instances by scheduling class methods for execution. The methods are weaved in an order that this specified on the method definition (after/before constraints). One major benefit is that additional behaviours can be weaved onto existing targets without modifying the build scripts. This approach is comparable to the CSS class declations in the web design context.
+The Waf *feature* system provides a way to weave specific behaviors onto existing targets (task generators) with minimum changes to the build scripts. The main benefits are flexibility and reduced maintenance efforts. This approach is comparable to the CSS class declarations in the web design context.
 
-The Waf features are declared by annotating functions with a decorators
-:py:func:`waflib.TaskGen.feature`. These functions are then mapped
-as class methods onto :py:class:`waflib.TaskGen.task_gen` with the name given.
+The *features* themselves are declared by annotating functions with a name
+through a specific Python decorator function :py:func:`waflib.TaskGen.feature`.
+This decorator then binds the given functions as class methods
+onto the Task generator class :py:class:`waflib.TaskGen.task_gen.
 
 The association between feature names and methods is *many-to-many*; in other words
 a method may be used by in several features, and that a feature may reference
-to several methods.
-
-Here is how to create and use a new feature named **foo**::
+to several methods. Here is for example how to bind the function *print_hello*
+to the feature named **foo**::
 
 	from waflib.TaskGen import feature
 	@feature('foo')
 	def print_hello(self):
 		print("Hello, World!")
 
-The function *print_hello* is now associated with the :py:class:`waflib.TaskGen.task_gen` class, which means
-that it may be used directly::
+Since the function *print_hello* is now associated with the :py:class:`waflib.TaskGen.task_gen` class,
+it becomes usable as method::
 
 	def build(bld):
 		tg = bld()
 		tg.print_hello()
 
-The method may be called directly, and several times. If a method creates task, the same tasks will be created
-more than once, which may cause build errors. The *feature* attribute is used to have the associated 
-methods called *exactly once* before the build starts::
+Calling such methods directly is problematic as it interferes with partial
+build declarations and with target dependencies.
+The *feature* attribute enables the methods to be called *exactly once*
+before the build starts and in a purely declarative matter::
 
 	def build(bld):
 		bld(features='foo')
 
-Here is a more complete example with two methods::
+When several methods are involved, the order of execution must be specified,
+else the methods are sorted by alphabetical order::
 
 	from waflib.TaskGen import feature, after_method
 
@@ -45,11 +47,10 @@ Here is a more complete example with two methods::
 	def build(bld):
 		bld(features='foo bar')
 
-The order of method execution is unrelated to the order of the features given. For instance,
-this example will print "Hello, Bar!" then "Hello, Foo!". The decorators
-:py:func:`waflib.TaskGen.after` and :py:func:`waflib.TaskGen.before` are
-enforcing partial order constraints on the methods to execute.
+The order of method execution is unrelated to the order of the features given though.
+For instance, this example will print "Hello, Bar!" then "Hello, Foo!".
 
-The following maps represent the associations betwen feature methods (represented in yellow) and
-methods associated to other feature names.
+The following maps represent the associations between feature methods (represented
+in yellow) and methods associated to other feature names. The arrows represent
+constraints over the order of execution.