document the __INSTANCE__ thing being pushed back to CMOP

diff --git a/lib/Class/MOP/Class.pm b/lib/Class/MOP/Class.pm
index 57be069..8bc3802 100644 (file)
--- a/lib/Class/MOP/Class.pm
+++ b/lib/Class/MOP/Class.pm
@@ -1417,7 +1417,11 @@ does nothing; it is merely a hook.
 
 This method is used to create a new object of the metaclass's
 class. Any parameters you provide are used to initialize the
-instance's attributes.
+instance's attributes. A special C<__INSTANCE__> key can be passed to
+provide an already generated instance, rather than having Moose
+generate it for you. This is mostly useful for using Class::MOP with
+foreign classes, which generally generate instances using their own
+constructor. See L<Moose::Cookbook::Basics::Recipe11> for more information.
 
 =item B<< $metaclass->instance_metaclass >>