Additional pod cleanups

[catagits/Catalyst-Action-REST.git] / lib / Catalyst / Controller / REST.pm

diff --git a/lib/Catalyst/Controller/REST.pm b/lib/Catalyst/Controller/REST.pm
index 2cd5f47..b77eb61 100644 (file)
--- a/lib/Catalyst/Controller/REST.pm
+++ b/lib/Catalyst/Controller/REST.pm
@@ -12,8 +12,10 @@ Catalyst::Controller::REST - A RESTful controller
 =head1 SYNOPSIS
 
     package Foo::Controller::Bar;
-
-    use base 'Catalyst::Controller::REST';
+    use Moose;
+    use namespace::autoclean;
+    
+    BEGIN { extends 'Catalyst::Controller::REST' }
 
     sub thing : Local : ActionClass('REST') { }
 
@@ -76,12 +78,12 @@ If we do not have (or cannot run) a serializer for a given content-type, a 415
 
 To make your Controller RESTful, simply have it
 
-  BEGIN {extends 'Catalyst::Controller::REST'; }
-
-Or if you use pre-Moose Catalyst versions,
+  BEGIN { extends 'Catalyst::Controller::REST' }
 
-  use parent 'Catalyst::Controller::REST';
+=head1 CONFIGURATION
 
+See L<Catalyst::Action::Serialize/CONFIGURATION>. Note that the C<serialize>
+key has been deprecated.
 
 =head1 SERIALIZATION
 
@@ -90,7 +92,7 @@ responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
 which serializer to use by mapping a content-type to a Serialization module.
 We select the content-type based on:
 
-=over 2
+=over
 
 =item B<The Content-Type Header>
 
@@ -107,7 +109,6 @@ it and use the best-ranked choice.
 
 =back
 
-
 =head1 AVAILABLE SERIALIZERS
 
 A given serialization mechanism is only available if you have the underlying
@@ -174,12 +175,37 @@ you serialize be a HASHREF, we transform outgoing data to be in the form of:
 =item * L<View>
 
 Uses a regular Catalyst view.  For example, if you wanted to have your
-C<text/html> and C<text/xml> views rendered by TT:
+C<text/html> and C<text/xml> views rendered by TT, set:
 
-  'text/html' => [ 'View', 'TT' ],
-  'text/xml'  => [ 'View', 'XML' ],
+  __PACKAGE__->config(
+      map => {
+          'text/html' => [ 'View', 'TT' ],
+          'text/xml'  => [ 'View', 'XML' ],
+      }
+  );
+
+Your views should have a C<process> method like this:
 
-Will do the trick nicely.
+  sub process {
+      my ( $self, $c, $stash_key ) = @_;
+
+      my $output;
+      eval {
+          $output = $self->serialize( $c->stash->{$stash_key} );
+      };
+      return $@ if $@;
+
+      $c->response->body( $output );
+      return 1;  # important
+  }
+  
+  sub serialize {
+      my ( $self, $data ) = @_;
+
+      my $serialized = ... process $data here ...
+
+      return $serialized;
+  }
 
 =back
 
@@ -188,7 +214,7 @@ C<415 Unsupported Media Type> response if an attempt to use an unsupported
 content-type is made.  You can ensure that something is always returned by
 setting the C<default> config option:
 
-  __PACKAGE__->config->{'default'} = 'text/x-yaml';
+  __PACKAGE__->config(default => 'text/x-yaml');
 
 would make it always fall back to the serializer plugin defined for
 C<text/x-yaml>.
@@ -215,7 +241,7 @@ refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
 These routines are all implemented as regular subroutines, and as
 such require you pass the current context ($c) as the first argument.
 
-=over 4
+=over
 
 =cut
 
@@ -524,15 +550,9 @@ Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 
 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
 
-=head1 AUTHOR
-
-Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
-
-Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
-
-=head1 MAINTAINER
+=head1 AUTHORS
 
-J. Shirley <jshirley@cpan.org>
+See L<Catalyst::Action::REST> for authors.
 
 =head1 LICENSE