make make_mutable always return $self and alter tests to verify this;…

… update docs to say that the return value is true but not to rely on its specific nature other than that

Changes

@@ -3,6 +3,9 @@ for, noteworthy changes.
 
 {{$NEXT}}
 
+  * Make make_immutable return value consistent and document it to be true.
+    (mst)
+
 2.0301 Fri, Oct 21, 2011
 
   [BUG FIXES]

lib/Class/MOP/Class.pm

@@ -1274,7 +1274,7 @@ sub _immutable_options {
 sub make_immutable {
     my ( $self, @args ) = @_;
 
-    return unless $self->is_mutable;
+    return $self unless $self->is_mutable;
 
     my ($file, $line) = (caller)[1..2];
 
@@ -1977,7 +1977,8 @@ of the inlining features than Class::MOP itself does.
 =item B<< $metaclass->make_immutable(%options) >>
 
 This method will create an immutable transformer and use it to make
-the class and its metaclass object immutable.
+the class and its metaclass object immutable, and returns true
+(you should not rely on the details of this value apart from its truth).
 
 This method accepts the following options:
 

t/cmop/immutable_metaclass.t

@@ -45,9 +45,11 @@ use Class::MOP;
         'immutable_options is empty before a class is made_immutable'
     );
 
-    $meta->make_immutable;
+    is( $meta->make_immutable, $meta, 'make_immutable returns $self' );
     my $line = __LINE__ - 1;
 
+    is( $meta->make_immutable, $meta, 'make_immutable returns $self again' );
+
     my $immutable_metaclass = $meta->_immutable_metaclass->meta;
 
     my $immutable_class_name = $immutable_metaclass->name;
@@ -145,7 +147,7 @@ use Class::MOP;
         $meta->make_immutable();
     }, undef, '... changed Bar to be immutable' );
 
-    ok( !$meta->make_immutable, '... make immutable now returns nothing' );
+    is( $meta->make_immutable, $meta, '... make immutable returns $meta' );
 
     ok( !$meta->is_mutable,  '... our class is no longer mutable' );
     ok( $meta->is_immutable, '... our class is now immutable' );
@@ -209,7 +211,7 @@ use Class::MOP;
         $meta->make_immutable();
     }, undef, '... changed Baz to be immutable' );
 
-    ok( !$meta->make_immutable, '... make immutable now returns nothing' );
+    is( $meta->make_immutable, $meta, '... make immutable returns $meta' );
 
     ok( !$meta->is_mutable,  '... our class is no longer mutable' );
     ok( $meta->is_immutable, '... our class is now immutable' );

t/cmop/make_mutable.t

@@ -48,7 +48,7 @@ use Class::MOP;
     is( exception {$meta->make_immutable; }, undef, '... changed Baz to be immutable' );
     ok(!$meta->is_mutable,              '... our class is no longer mutable');
     ok($meta->is_immutable,             '... our class is now immutable');
-    ok(!$meta->make_immutable,          '... make immutable now returns nothing');
+    is($meta->make_immutable, $meta,    '... make immutable returns $meta');
     ok($meta->get_method('new'),        '... inlined constructor created');
     ok($meta->has_method('new'),        '... inlined constructor created for sure');
     is_deeply([ map { $_->name } $meta->_inlined_methods ], [ 'new' ], '... really, i mean it');
@@ -136,7 +136,7 @@ use Class::MOP;
             }, undef, '... changed class to be immutable' );
     ok(!$meta->is_mutable,                    '... our class is no longer mutable');
     ok($meta->is_immutable,                   '... our class is now immutable');
-    ok(!$meta->make_immutable,                '... make immutable now returns nothing');
+    is($meta->make_immutable, $meta,          '... make immutable returns $meta');
 
     is( exception { $meta->make_mutable }, undef, '... changed Baz to be mutable' );
     ok($meta->is_mutable,             '... our class is mutable');