[libbread-board-perl] 06/66: doc editing

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to branch master
in repository libbread-board-perl.

commit bb5029b6dcff0e24608cf814cd4909653c166d3d
Author: Jesse Luehrs <doy at tozt.net>
Date:   Fri Jul 20 22:49:08 2012 -0500

    doc editing
---
 lib/Bread/Board.pm |   77 +++++++++++++++++++++++++++++++---------------------
 1 file changed, 46 insertions(+), 31 deletions(-)

diff --git a/lib/Bread/Board.pm b/lib/Bread/Board.pm
index ad0b39f..b4ca55c 100644
--- a/lib/Bread/Board.pm
+++ b/lib/Bread/Board.pm
@@ -318,24 +318,23 @@ Want to know more? See the L<Bread::Board::Manual>.
   +-----------------------------------------+
 
 Loading this package will automatically load the rest of the packages needed by
-any Bread::Board configuration.
-  
+your Bread::Board configuration.
+
 =head1 EXPORTED FUNCTIONS
 
 The functions of this package provide syntactic sugar to help you build your
 Bread::Board configuration. You can build such a configuration by constructing
-each of the classes directly instead, but your code may be more difficult to
+the objects manually instead, but your code may be more difficult to
 understand.
 
 =over 4
 
 =item I<container ($name, &body)>
 
-This function provides a shortcut for defining your containers. This function
-constructs and returns an instance of L<Bread::Board::Container>. The C<&body>
-block may be used to add services or sub-containers within the newly constructed
-container. The block is optional. Usually, the block is not passed direclty, but
-passed using the C<as> function.
+This function constructs and returns an instance of L<Bread::Board::Container>.
+The (optional) C<&body> block may be used to add services or sub-containers
+within the newly constructed container. Usually, the block is not passed
+directly, but passed using the C<as> function.
 
 For example,
 
@@ -349,10 +348,11 @@ For example,
 
 In many cases, subclassing L<Bread::Board::Container> is the easiest route to
 getting access to this framework. You can do this and still get all the
-benefites of the syntactic sugar for configuring that class by passing an
-instance of your contianer subclass to C<container>.
+benefits of the syntactic sugar for configuring that class by passing an
+instance of your container subclass to C<container>.
 
-You could, for example, configure your container inside the C<BUILD> method of your class.
+You could, for example, configure your container inside the C<BUILD> method of
+your class:
 
   package MyWebApp;
   use Moose;
@@ -369,7 +369,7 @@ You could, for example, configure your container inside the C<BUILD> method of y
 
 =item I<container ($name, [ @parameters ], &body)>
 
-A third way of using the C<container> method is to build a parameterized
+A third way of using the C<container> function is to build a parameterized
 container. These are useful as a way of providing a placeholder for parts of
 the configuration that may be provided later. You may not use an instance
 object in place of the C<$name> in this case.
@@ -385,10 +385,10 @@ defining containers.
 =item I<service ($name, $literal | %service_description)>
 
 Within the C<as> blocks for your containers, you may construct services using
-the C<service> function. This will construct any kind of service based upon
-how it is defined.
+the C<service> function. This can construct several different kinds of services
+based upon how it is called.
 
-To build a literal service using L<Bread::Board::Literal>, just specify a
+To build a literal service (a L<Bread::Board::Literal> object), just specify a
 scalar value or reference you want to use as the literal value:
 
   # In case you need to adjust the gravitational constant of the Universe
@@ -404,7 +404,7 @@ details required to use that sort of injection:
           MyApp::Search->new($s->param('url'), $s->param('type'));
       },
       dependencies => {
-          url => 'http://example.com/search',
+          url => 'search_url',
       },
       parameters => {
           type => { isa => 'Str', default => 'text' },
@@ -417,15 +417,18 @@ instance, this is useful if you need to use L<Bread::Board::SetterInjection>
 or have defined a custom injection service.  If you specify a C<block>, block
 injection will be performed using L<Bread::Board::BlockInjection>. If neither
 of these is present, constructor injection will be used with
-L<Bread::Board::ConstructorInjection>.
-      
+L<Bread::Board::ConstructorInjection> (and you must provide the C<class>
+option).
+
 =item I<depends_on ($service_path)>
 
-The C<depends_on> function creates a L<Bread::Board::Dependency> object for the named C<$service_path> and returns it.
+The C<depends_on> function creates a L<Bread::Board::Dependency> object for the
+named C<$service_path> and returns it.
 
 =item I<wire_names (@service_names)>
 
-This function is just a shortcut for passing a hash reference of dependencies into the service.
+This function is just a shortcut for passing a hash reference of dependencies
+into the service.
 
   service foo => (
       class => "Pity::TheFoo',
@@ -445,29 +448,37 @@ The above is identical to:
 
 =item I<typemap ($type, $service | $service_path)>
 
-This feature is new (read: experimental).
-
-This creates a type mapping for the named type. Typically, it is paired with the C<infer> call like so:
+This creates a type mapping for the named type. Typically, it is paired with
+the C<infer> call like so:
 
   typemap 'MyApp::Model::UserAccount' => infer;
 
-For more details on what type mapping is and how it works, see L<Bread::Board::Manual::Concepts::Typemap>.
+For more details on what type mapping is and how it works, see
+L<Bread::Board::Manual::Concepts::Typemap>.
 
 =item I<infer (?%hints)>
 
-This is used with C<typemap> to help create the typemap inference. It can be used with no arguments to do everything automatically. However, in some cases, you may want to pass a service instance as the argument or a hash of service arguments to change how the type map works. For example, if your type needs to be constructed using a setter injection, you can use an inference similar to this:
+This is used with C<typemap> to help create the typemap inference. It can be
+used with no arguments to do everything automatically. However, in some cases,
+you may want to pass a service instance as the argument or a hash of service
+arguments to change how the type map works. For example, if your type needs to
+be constructed using a setter injection, you can use an inference similar to
+this:
 
-  typemap 'MyApp::Model::UserPassword' => infer( service_class => 'Bread::Board::SetterInjection' );
+  typemap 'MyApp::Model::UserPassword' => infer(
+      service_class => 'Bread::Board::SetterInjection',
+  );
 
-For more details on what type mapping is and how it works, see L<Bread::Board::Manual::Concepts::Typemap>.
+For more details on what type mapping is and how it works, see
+L<Bread::Board::Manual::Concepts::Typemap>.
 
 =item I<include ($file)>
 
-This is a shortcut for loading another Bread::Board configuration from another file. 
+This is a shortcut for loading a Bread::Board configuration from another file.
 
   include "filename.pl";
 
-The above pretty much identical to running:
+The above is pretty much identical to running:
 
   do "filename.pl";
 
@@ -475,7 +486,10 @@ However, you might find it more readable to use C<include>.
 
 =item I<alias ($service_name, $service_path, %service_description)>
 
-This helper allows for the creation of service aliases, which allows you to define a service in one place and then res-use that service with a different name somewhere else. This is sort of like a symbolic link for services. Aliases will be resolved recursively, so an alias can alias an alias.
+This helper allows for the creation of service aliases, which allows you to
+define a service in one place and then reuse that service with a different name
+somewhere else. This is sort of like a symbolic link for services. Aliases will
+be resolved recursively, so an alias can alias an alias.
 
 For example,
 
@@ -495,7 +509,8 @@ These are not exported, but might be helpful to you.
 
 =item I<set_root_container ($container)>
 
-You may use this to set a top-level root container for all container definitions. 
+You may use this to set a top-level root container for all container
+definitions.
 
 For example,
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libbread-board-perl.git