meta instance doc improvements

diff --git a/lib/Moose/Meta/Instance.pm b/lib/Moose/Meta/Instance.pm
index e8d8a38..0e9baac 100644 (file)
--- a/lib/Moose/Meta/Instance.pm
+++ b/lib/Moose/Meta/Instance.pm
@@ -19,12 +19,22 @@ __END__
 
 Moose::Meta::Instance - The Moose Instance metaclass
 
+=head1 SYNOPSIS
+
+    # nothing to see here
+
 =head1 DESCRIPTION
 
-This is a stub mostly, but I know I will want to use it later on.
+This class provides the low level data storage abstractions for attributes.
+
+Using this API generally violates attribute encapsulation and is not
+reccomended, instead look at L<Class::MOP::Attribute/get_value>,
+L<Class::MOP::Attribute/set_value>, etc, as well as L<Moose::Meta::Attribute>
+for the reccomended way to fiddle with attribute values in a generic way,
+independant of how/whether accessors have been defined. Accessors can be found
+using L<Class::MOP::Class/get_attribute>.
 
-See the L<Class::MOP::Instance> docs for details on the instance 
-protocol.
+See the L<Class::MOP::Instance> docs for details on the instance protocol.
 
 =head1 BUGS