From: Vincent Pit <vince@profvince.com>
Date: Sun, 1 Aug 2010 21:02:42 +0000 (+0200)
Subject: More docs for LT::Functor/LT::Functor::Rule
X-Git-Tag: v0.02~10
X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FLaTeX-TikZ.git;a=commitdiff_plain;h=2f8d25c7ced8c8bc43802025240ab7d673892f5d

More docs for LT::Functor/LT::Functor::Rule
---

diff --git a/lib/LaTeX/TikZ/Functor.pm b/lib/LaTeX/TikZ/Functor.pm
index d4ba074..00c441a 100644
--- a/lib/LaTeX/TikZ/Functor.pm
+++ b/lib/LaTeX/TikZ/Functor.pm
@@ -18,7 +18,32 @@ our $VERSION = '0.01';
 =head1 DESCRIPTION
 
 A functor takes a L<LaTeX::TikZ::Set> tree and clones it according to certain rules.
-Rules can apply not only to L<LaTeX::TikZ::Set> objects, but also to the L<LaTeX::TikZ::Mod> objects they contain.
+
+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.
+
+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 :
+
+=over 4
+
+=item *
+
+the functor object as its first argument ;
+
+=item *
+
+the current set object as its second argument ;
+
+=item *
+
+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.
+
+If no matching rule is found, the object is returned as-is.
 
 =cut
 
@@ -209,7 +234,7 @@ sub default_rule {
 
 =head1 SEE ALSO
 
-L<LaTeX::TikZ>.
+L<LaTeX::TikZ>, L<LaTeX::TikZ::Functor::Rule>.
 
 =head1 AUTHOR
 
diff --git a/lib/LaTeX/TikZ/Functor/Rule.pm b/lib/LaTeX/TikZ/Functor/Rule.pm
index efaff7b..15cc489 100644
--- a/lib/LaTeX/TikZ/Functor/Rule.pm
+++ b/lib/LaTeX/TikZ/Functor/Rule.pm
@@ -17,7 +17,7 @@ our $VERSION = '0.01';
 
 =head1 DESCRIPTION
 
-A rule specifies how functors should handle a certain kind of set or mod.
+A rule specifies how functors (L<LaTeX::TikZ::Functor> objects) should handle a certain kind of set or mod.
 A functor is basically an ordered collection of rules.
 
 =cut
@@ -32,6 +32,9 @@ use Any::Moose 'Util::TypeConstraints';
 
 =head2 C<target>
 
+A class or role name against which set or mod candidates will be matched.
+It must consume either L<LaTeX::TikZ::Set> or L<LaTeX::TikZ::Mod>, directly or through inheritance.
+
 =cut
 
 has 'target' => (
@@ -42,6 +45,9 @@ has 'target' => (
 
 =head2 C<handler>
 
+The code reference executed when the rule handles a given set or mod object.
+It is called with the L<LaTeX::TikZ::Functor> object as its first argument, the set/mod object as its second, and then the arguments passed to the functor itself.
+
 =cut
 
 has 'handler' => (
@@ -52,6 +58,8 @@ has 'handler' => (
 
 =head2 C<is_role>
 
+True if and only if the target is a role.
+
 =cut
 
 has 'is_role' => (
@@ -62,6 +70,8 @@ has 'is_role' => (
 
 =head2 C<is_set>
 
+True when the target does the L<LaTeX::TikZ::Set> role, and false when it does L<LaTeX::TikZ::Mod>.
+
 =cut
 
 has 'is_set' => (
@@ -77,6 +87,8 @@ my $ltfrl_tc = subtype 'LaTeX::TikZ::Functor::RuleList'
 
 =head2 C<< new target => $target, handler => $handler >>
 
+Constructs a new rule object with target C<$target> and handler C<$handler>.
+
 =cut
 
 around 'BUILDARGS' => sub {