Rewrite functors description

diff --git a/lib/LaTeX/TikZ/Functor.pm b/lib/LaTeX/TikZ/Functor.pm
index 4aa811211b1d8d7fe94d5827b9b7894263a2d26b..f71ce6cd5a03fb90c6b44c43e5b1ba1407dbda5d 100644 (file)
--- a/lib/LaTeX/TikZ/Functor.pm
+++ b/lib/LaTeX/TikZ/Functor.pm
@@ -17,12 +17,14 @@ our $VERSION = '0.02';
 
 =head1 DESCRIPTION
 
-A functor takes a L<LaTeX::TikZ::Set> tree and clones it according to certain rules.
+A functor takes a L<LaTeX::TikZ::Set> tree and returns a new, transmuted version of it according to certain rules.
+It recursively visits all the nodes of the tree, building a new set out of the result of the functor on the child sets.
 
-Rules can apply not only to L<LaTeX::TikZ::Set> consumer objects, but also to the L<LaTeX::TikZ::Mod> consumer objects they contain.
-The are stored as L<LaTeX::TikZ::Functor::Rule> objects.
+Rules are stored as L<LaTeX::TikZ::Functor::Rule> objects.
+They can apply not only to L<LaTeX::TikZ::Set> consumer objects, but also to the L<LaTeX::TikZ::Mod> consumer objects they contain.
+When the functor is called against a set object and that the returned set is different from the original (as told by C<==>, which defaults to object identity), then the functor is also applied to all the mods of the set, and their transformed counterparts are added to the new set.
 
-When the functor is called onto a set object, all its associated rules are tried successively, and the handler of the first matching rule is executed with :
+When the functor is called onto a set or mod object, all its associated rules are tried successively, and the handler of the first matching rule is executed with :
 
 =over 4
 
@@ -32,7 +34,7 @@ the functor object as its first argument ;
 
 =item *
 
-the current set object as its second argument ;
+the current set or mod object as its second argument ;
 
 =item *
 
@@ -40,8 +42,7 @@ the arguments passed to the functor itself starting at the third argument.
 
 =back
 
-The handler is expected to return the new set/mod that will in the resulting set tree.
-If the new set is different from the original, then the functor is applied to all the mods of the set, and their cloned version are added to the new set.
+The handler is expected to return the new set or mod that will replace the old one in the resulting set tree.
 
 If no matching rule is found, the object is returned as-is.
 
@@ -81,7 +82,7 @@ BEGIN {
 
 =head2 C<< new rules => [ $spec1 => $handler1, $spec2 => $handler2, ... ] >>
 
-Creates a new functor object that will use both the default and these user-specified rules.
+Creates a new functor object that will use both the default and the user-specified rules.
 The functor is also a code reference that expects to be called against L<LaTeX::TikZ::Set> objects.
 
 The default set and mod rules clone their relevant objects, so you get a clone functor (for the default set types) if you don't specify any user rule.
@@ -207,7 +208,7 @@ LaTeX::TikZ::Interface->register(
 
 Adds to all subsequently created functors a default rule for the class or role C<$spec>.
 
-An exception is thrown if there is already a default rule for C<$spec> ; otherwise, the new rule is appended to the current list of rules.
+An exception is thrown if there is already a default rule for C<$spec> ; otherwise, the new rule is appended to the current list of default rules.
 But if C<$spec> begins with C<'+'>, the rule will replace I<all> default rules that apply to subclasses or subroles of C<$spec> (including C<$spec> itself).
 
 Returns true if and only if an existent rule was replaced.