From: Dave Rolsky <autarch@urth.org>
Date: Mon, 19 May 2008 15:22:35 +0000 (+0000)
Subject: Try to clarify when builder methods are called, and what their
X-Git-Tag: 0_55~162
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e89d3090fc6248435dd895c6c69e7ca189aef083;p=gitmo%2FMoose.git

Try to clarify when builder methods are called, and what their
invocant is.
---

diff --git a/lib/Moose/Cookbook/Recipe9.pod b/lib/Moose/Cookbook/Recipe9.pod
index c58bd3f..9ccf92a 100644
--- a/lib/Moose/Cookbook/Recipe9.pod
+++ b/lib/Moose/Cookbook/Recipe9.pod
@@ -52,10 +52,21 @@ If you've already read L<Moose::Cookbook::Recipe3>, then this example
 should look awfully familiar. In fact, all we've done here is replace
 the attribute C<default> with a C<builder> method.
 
-In this particular case, the C<default> and C<builder> act exactly the
-same. When the C<left> or C<right> attribute is first accessed before
-it has been set, Moose will call the specified C<builder> method to
-populate the attribute.
+In this particular case, the C<default> and C<builder> options act in
+exactly the same way. When the C<left> or C<right> attribute get
+method is called, Moose will call the builder method to initialize the
+attribute.
+
+Note that Moose calls the builder method I<on the object which has the
+attribute>. Here's an example in code:
+
+  my $tree = BinaryTree->new();
+
+  my $left = $tree->left();
+
+At this point, Moose will call C<< $tree->_build_child_tree() >> in
+order to populate the C<left> attribute. If we had passed C<left> to
+the original constructor, the builer would not be called.
 
 =head2 Subclassable