From: Dave Rolsky <autarch@houseabsolute.urth.org>
Date: Tue, 24 Mar 2009 20:55:41 +0000 (-0500)
Subject: I started documenting this stuff but then my head blew up. I'm
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=refs%2Fheads%2Fattic%2Faborted-role-application-docs;p=gitmo%2FMoose.git

I started documenting this stuff but then my head blew up. I'm
commiting this here for future reference.
---

diff --git a/lib/Moose/Meta/Role/Application.pm b/lib/Moose/Meta/Role/Application.pm
index 7111601..dcbfd28 100644
--- a/lib/Moose/Meta/Role/Application.pm
+++ b/lib/Moose/Meta/Role/Application.pm
@@ -94,29 +94,76 @@ Moose::Meta::Role::Application - A base class for role application
 
 =head1 DESCRIPTION
 
-This is the abstract base class for role applications.
+This is the abstract base class for role applications. Role
+application is the logic of composing a role into something. That
+something could be a class, another role, or an object instance.
 
 =head2 METHODS
 
 =over 4
 
-=item B<new>
+=item B<< Moose::Meta::Role::Application->new(%options) >>
 
-=item B<meta>
+This method returns a new role application. It accepts several
+options:
+
+=over 8
+
+=item * excludes
+
+This is an optional array reference of methods to be excluded when
+applying the role.
+
+=item * alias
+
+This is an optional hash reference of methods to be renamed when
+applying the role. The keys are the original method names, and the
+values are the new method names.
+
+=back
+
+Note that the constructor does not actually take any roles as
+arguments.
+
+=item B<< $application->get_method_exclusions >>
 
-=item B<get_method_exclusions>
+Returns an array reference containing the names of the excluded
+methods.
 
-=item B<is_method_excluded>
+=item B<< $application->is_method_excluded($method_name) >>
 
-=item B<get_method_aliases>
+Given a method name, returns true if the method is excluded.
 
-=item B<is_aliased_method>
+=item B<< $application->get_method_aliases >>
 
-=item B<is_method_aliased>
+Returns the hash reference of method aliases passed to the
+constructor.
 
-=item B<apply>
+=item B<< $application->is_aliased_method($method_name) >>
 
-=item B<check_role_exclusions>
+This takes the name of the original method, and returns true if it is
+aliased.
+
+=item B<< $application->is_method_aliased($method_name) >>
+
+Returns true if the method name given is being used as the I<new> name
+for any method.
+
+=item B<< $application->apply($role, $thing) >>
+
+This method implements the logic of role application by calling the
+various check and apply methods below. Any arguments passed to this
+method are simply passed on to the other methods, without any
+processing.
+
+The first argument is always a L<Moose::Meta::Role> object, and the
+second is the thing to which the role is being applied.
+
+In some cases, the second
+
+=item B<< $application->check_role_exclusions(...) >>
+
+A virtual method. Subclasses are expected to throw an error if 
 
 =item B<check_required_methods>
 
@@ -136,6 +183,8 @@ This is the abstract base class for role applications.
 
 =item B<apply_override_method_modifiers>
 
+=item B<meta>
+
 =back
 
 =head1 BUGS