add docs

7 files changed, 143 insertions, 0 deletions

diff --git a/lib/Bread/Board/Declare.pm b/lib/Bread/Board/Declare.pm
index 93f063d..0a94e2a 100644
--- a/lib/Bread/Board/Declare.pm
+++ b/lib/Bread/Board/Declare.pm
@@ -7,10 +7,105 @@ use Bread::Board ();
 =head1 SYNOPSIS
 
   package MyApp;
+  use Moose;
   use Bread::Board::Declare;
 
+  has dsn => (
+      is    => 'ro',
+      isa   => 'Str',
+      value => 'dbi:mysql:my_db',
+  );
+
+  has dbic => (
+      is           => 'ro',
+      isa          => 'MyApp::Model::DBIC',
+      dependencies => ['dsn'],
+      lifecycle    => 'Singleton',
+  );
+
+  has tt => (
+      is  => 'ro',
+      isa => 'MyApp::View::TT',
+  );
+
+  has controller => (
+      is           => 'ro',
+      isa          => 'MyApp::Controller',
+      dependencies => {
+          model => 'dbic',
+          view  => 'tt',
+      },
+  );
+
+  MyApp->new->controller; # new controller object with new model and view
+  MyApp->new(
+      model => MyApp::Model::KiokuDB->new,
+  )->controller; # new controller object with new view and kioku model
+
 =head1 DESCRIPTION
 
+This module is a L<Moose> extension which allows for declaring L<Bread::Board>
+container classes in a more straightforward and natural way. It sets up
+L<Bread::Board::Container> as the superclass, and creates services associated
+with each attribute that you create, according to these rules:
+
+=over 4
+
+=item
+
+If the C<< service => 0 >> option is passed to C<has>, no service is created.
+
+=item
+
+If the C<value> option is passed to C<has>, a L<Bread::Board::Literal>
+service is created, with the given value.
+
+=item
+
+If the C<block> option is passed to C<has>, a L<Bread::Board::BlockInjection>
+service is created, with the given coderef as the block. In addition to
+receiving the service object (as happens in Bread::Board), this coderef will
+also be passed the container object.
+
+=item
+
+If the attribute has a type constraint corresponding to a class, a
+L<Bread::Board::ConstructorInjection> service is created, with the class
+corresponding to the type constraint.
+
+=item
+
+Otherwise, no service is created.
+
+=back
+
+Constructor parameters for services (C<dependencies>, C<lifecycle>, etc) can
+also be passed into the attribute definition; these will be forwarded to the
+service constructor.
+
+In addition to creating the services, this module also modifies the attribute
+reader generation, so that if the attribute has no value, a value will be
+resolved from the associated service. It also modifies the C<get> method on
+services so that if the associated attribute has a value, that value will be
+returned immediately. This allows for overriding service values by passing
+replacement values into the constructor, or by calling setter methods.
+
+Note that C<default>/C<builder> doesn't make a lot of sense in this setting, so
+they are explicitly disabled. In addition, multiple inheritance would just
+cause a lot of problems, so it is also disabled (although single inheritance
+and role application works properly).
+
+NOTE: When using this module in roles with Moose versions prior to 2.0, the
+attribute trait will need to be applied explicitly to attributes that should
+become services, as in:
+
+  has attr => (
+      traits => ['Service'],
+      is     => 'ro',
+      isa    => 'Str',
+      value  => 'value',
+  )
+
 =cut
 
 my (undef, undef, $init_meta) = Moose::Exporter->build_import_methods(
diff --git a/lib/Bread/Board/Declare/BlockInjection.pm b/lib/Bread/Board/Declare/BlockInjection.pm
index 4ea4f56..7ff4a9f 100644
--- a/lib/Bread/Board/Declare/BlockInjection.pm
+++ b/lib/Bread/Board/Declare/BlockInjection.pm
@@ -4,6 +4,10 @@ use Moose;
 
 =head1 DESCRIPTION
 
+This is a custom subclass of L<Bread::Board::BlockInjection> which does the
+L<Bread::Board::Declare::Role::Service> role. See those two modules for more
+details.
+
 =cut
 
 extends 'Bread::Board::BlockInjection';
diff --git a/lib/Bread/Board/Declare/ConstructorInjection.pm b/lib/Bread/Board/Declare/ConstructorInjection.pm
index 3d2a2c5..32b6f95 100644
--- a/lib/Bread/Board/Declare/ConstructorInjection.pm
+++ b/lib/Bread/Board/Declare/ConstructorInjection.pm
@@ -4,6 +4,10 @@ use Moose;
 
 =head1 DESCRIPTION
 
+This is a custom subclass of L<Bread::Board::ConstructorInjection> which does
+the L<Bread::Board::Declare::Role::Service> role. See those two modules for
+more details.
+
 =cut
 
 extends 'Bread::Board::ConstructorInjection';
diff --git a/lib/Bread/Board/Declare/Literal.pm b/lib/Bread/Board/Declare/Literal.pm
index c2269b1..a8574d2 100644
--- a/lib/Bread/Board/Declare/Literal.pm
+++ b/lib/Bread/Board/Declare/Literal.pm
@@ -4,6 +4,10 @@ use Moose;
 
 =head1 DESCRIPTION
 
+This is a custom subclass of L<Bread::Board::Literal> which does the
+L<Bread::Board::Declare::Role::Service> role. See those two modules for more
+details.
+
 =cut
 
 extends 'Bread::Board::Literal';
diff --git a/lib/Bread/Board/Declare/Meta/Role/Attribute.pm b/lib/Bread/Board/Declare/Meta/Role/Attribute.pm
index 82d90db..4ae6a94 100644
--- a/lib/Bread/Board/Declare/Meta/Role/Attribute.pm
+++ b/lib/Bread/Board/Declare/Meta/Role/Attribute.pm
@@ -12,10 +12,15 @@ use Bread::Board::Declare::Literal;
 
 =head1 DESCRIPTION
 
+This role adds functionality to the attribute metaclass for
+L<Bread::Board::Declare> objects.
+
 =cut
 
 =attr service
 
+Whether or not to create a service for this attribute. Defaults to true.
+
 =cut
 
 has service => (
@@ -26,6 +31,8 @@ has service => (
 
 =attr block
 
+The block to use when creating a L<Bread::Board::BlockInjection> service.
+
 =cut
 
 has block => (
@@ -36,6 +43,9 @@ has block => (
 
 =attr literal_value
 
+The value to use when creating a L<Bread::Board::Literal> service. Note that
+the parameter that should be passed to C<has> is C<value>.
+
 =cut
 
 # has_value is already a method
@@ -48,6 +58,9 @@ has literal_value => (
 
 =attr lifecycle
 
+The lifecycle to use when creating the service. See L<Bread::Board::Service>
+and L<Bread::Board::LifeCycle>.
+
 =cut
 
 has lifecycle => (
@@ -58,6 +71,9 @@ has lifecycle => (
 
 =attr dependencies
 
+The dependency specification to use when creating the service. See
+L<Bread::Board::Service::WithDependencies>.
+
 =cut
 
 has dependencies => (
@@ -69,6 +85,9 @@ has dependencies => (
 
 =attr constructor_name
 
+The constructor name to use when creating L<Bread::Board::ConstructorInjection>
+services. Defaults to C<new>.
+
 =cut
 
 has constructor_name => (
@@ -79,6 +98,8 @@ has constructor_name => (
 
 =attr associated_service
 
+The service object that is associated with this attribute.
+
 =cut
 
 has associated_service => (
diff --git a/lib/Bread/Board/Declare/Meta/Role/Class.pm b/lib/Bread/Board/Declare/Meta/Role/Class.pm
index 57a9db9..3ece152 100644
--- a/lib/Bread/Board/Declare/Meta/Role/Class.pm
+++ b/lib/Bread/Board/Declare/Meta/Role/Class.pm
@@ -7,10 +7,15 @@ use List::MoreUtils qw(any);
 
 =head1 DESCRIPTION
 
+This role adds functionality to the metaclass of L<Bread::Board::Declare>
+classes.
+
 =cut
 
 =method get_all_services
 
+Returns all of the services that are associated with attributes in this class.
+
 =cut
 
 sub get_all_services {
diff --git a/lib/Bread/Board/Declare/Role/Service.pm b/lib/Bread/Board/Declare/Role/Service.pm
index a428dfd..e0b36f9 100644
--- a/lib/Bread/Board/Declare/Role/Service.pm
+++ b/lib/Bread/Board/Declare/Role/Service.pm
@@ -4,10 +4,17 @@ use Moose::Role;
 
 =head1 DESCRIPTION
 
+This role modifies L<Bread::Board::Service> objects for use in
+L<Bread::Board::Declare>. It holds a reference to the attribute object that the
+service is associated with, and overrides the C<get> method to prefer to return
+the value in the attribute, if it exists.
+
 =cut
 
 =attr associated_attribute
 
+The attribute metaobject that this service is associated with.
+
 =cut
 
 has associated_attribute => (
@@ -32,6 +39,9 @@ around get => sub {
 
 =method parent_container
 
+Returns the Bread::Board::Declare container object that this service is
+contained in.
+
 =cut
 
 sub parent_container {