document that auto_deref is wantarray-based

[gitmo/Moose.git] / lib / Moose / Manual / Attributes.pod

diff --git a/lib/Moose/Manual/Attributes.pod b/lib/Moose/Manual/Attributes.pod
index ff5af8b..66d9364 100644 (file)
--- a/lib/Moose/Manual/Attributes.pod
+++ b/lib/Moose/Manual/Attributes.pod
@@ -61,7 +61,7 @@ read and write the value of that attribute for an object.
 
 By default, the accessor method has the same name as the attribute. If
 you declared your attribute as C<ro> then your accessor will be
-read-only. If you declared it read-write, you get a read-write
+read-only. If you declared it as C<rw>, you get a read-write
 accessor. Simple.
 
 Given our C<Person> example above, we now have a single C<first_name>
@@ -441,7 +441,7 @@ writing). Second, it is also called when an attribute's value is
 passed to the constructor.
 
 However, triggers are I<not> called when an attribute is populated
-from a C<default> or C<builder>
+from a C<default> or C<builder>.
 
 =head2 Attribute types
 
@@ -606,16 +606,18 @@ it.
 
 If your attribute is an array reference or hash reference, the
 C<auto_deref> option will make Moose dereference the value when it is
-returned from the reader method:
+returned from the reader method I<in list context>:
 
   my %map = $object->mapping;
 
 This option only works if your attribute is explicitly typed as an
-C<ArrayRef> or C<HashRef>.
+C<ArrayRef> or C<HashRef>.  When the reader is called in I<scalar> context,
+the reference itself is returned.
 
 However, we recommend that you use L<Moose::Meta::Attribute::Native> traits
 for these types of attributes, which gives you much more control over how
-they are accessed and manipulated.
+they are accessed and manipulated. See also
+L<Moose::Manual::BestPractices#Use_Moose::Meta::Attribute::Native_traits_instead_of_auto_deref>.
 
 =head2 Initializer