improved documentation of content objects

mojolicious · Oct 19, 2011 · 225a38d · 225a38d
1 parent 590e098
commit 225a38d
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 35 deletions.
diff --git a/lib/Mojo/Content/MultiPart.pm b/lib/Mojo/Content/MultiPart.pm
@@ -241,9 +241,9 @@ Mojo::Content::MultiPart - HTTP 1.1 multipart content container
 
   use Mojo::Content::MultiPart;
 
-  my $content = Mojo::Content::MultiPart->new;
-  $content->parse('Content-Type: multipart/mixed; boundary=---foobar');
-  my $part = $content->parts->[4];
+  my $multi = Mojo::Content::MultiPart->new;
+  $multi->parse('Content-Type: multipart/mixed; boundary=---foobar');
+  my $part = $multi->parts->[4];
 
 =head1 DESCRIPTION
 
@@ -257,8 +257,8 @@ emit the following new ones.
 
 =head2 C<part>
 
-  $content->on(part => sub {
-    my ($content, $part) = @_;
+  $multi->on(part => sub {
+    my ($multi, $part) = @_;
   });
 
 Emitted when a new part starts.
@@ -271,7 +271,8 @@ and implements the following new ones.
 
 =head2 C<parts>
 
-  my $parts = $content->parts;
+  my $parts = $multi->parts;
+  $multi    = $multi->parts([]);
 
 Content parts embedded in this multipart content, usually
 L<Mojo::Content::Single> objects.
@@ -283,44 +284,44 @@ implements the following new ones.
 
 =head2 C<body_contains>
 
-  my $success = $content->body_contains('foobarbaz');
+  my $success = $multi->body_contains('foobarbaz');
 
 Check if content parts contain a specific string.
 
 =head2 C<body_size>
 
-  my $size = $content->body_size;
+  my $size = $multi->body_size;
 
 Content size in bytes.
 
 =head2 C<build_boundary>
 
-  my $boundary = $content->build_boundary;
+  my $boundary = $multi->build_boundary;
 
 Generate a suitable boundary for content.
 
 =head2 C<clone>
 
-  my $clone = $content->clone;
+  my $clone = $multi->clone;
 
 Clone content if possible.
 Note that this method is EXPERIMENTAL and might change without warning!
 
 =head2 C<get_body_chunk>
 
-  my $chunk = $content->get_body_chunk(0);
+  my $chunk = $multi->get_body_chunk(0);
 
 Get a chunk of content starting from a specfic position.
 
 =head2 C<is_multipart>
 
-  my $true = $content->is_multipart;
+  my $true = $multi->is_multipart;
 
 True.
 
 =head2 C<parse>
 
-  $content = $content->parse('Content-Type: multipart/mixed');
+  $multi = $multi->parse('Content-Type: multipart/mixed');
 
 Parse content chunk.
 

diff --git a/lib/Mojo/Content/Single.pm b/lib/Mojo/Content/Single.pm
@@ -48,10 +48,8 @@ sub parse {
 
   # Content needs to be upgraded to multipart
   if ($self->auto_upgrade && defined($self->boundary)) {
-    return $self if $self->isa('Mojo::Content::MultiPart');
-    my $multipart = Mojo::Content::MultiPart->new($self)->parse;
-    $self->emit(upgrade => $multipart);
-    return $multipart;
+    $self->emit(upgrade => my $multi = Mojo::Content::MultiPart->new($self));
+    return $multi->parse;
   }
 
   # Don't waste memory and upgrade to file based storage on demand
@@ -90,8 +88,8 @@ Mojo::Content::Single - HTTP 1.1 content container
 
   use Mojo::Content::Single;
 
-  my $content = Mojo::Content::Single->new;
-  $content->parse("Content-Length: 12\r\n\r\nHello World!");
+  my $single = Mojo::Content::Single->new;
+  $single->parse("Content-Length: 12\r\n\r\nHello World!");
 
 =head1 DESCRIPTION
 
@@ -105,8 +103,8 @@ emit the following new ones.
 
 =head2 C<upgrade>
 
-  $content->on(upgrade => sub {
-    my ($content, $multipart) = @_;
+  $single->on(upgrade => sub {
+    my ($single, $multi) = @_;
   });
 
 Emitted when content gets upgraded.
@@ -119,15 +117,15 @@ implements the following new ones.
 
 =head2 C<asset>
 
-  my $asset = $content->asset;
-  $content  = $content->asset(Mojo::Asset::Memory->new);
+  my $asset = $single->asset;
+  $single   = $single->asset(Mojo::Asset::Memory->new);
 
 The actual content, defaults to a L<Mojo::Asset::Memory> object.
 
 =head2 C<auto_upgrade>
 
-  my $upgrade = $content->auto_upgrade;
-  $content    = $content->auto_upgrade(0);
+  my $upgrade = $single->auto_upgrade;
+  $single     = $single->auto_upgrade(0);
 
 Try to detect multipart content and automatically upgrade to a
 L<Mojo::Content::MultiPart> object, defaults to C<1>.
@@ -140,32 +138,32 @@ implements the following new ones.
 
 =head2 C<body_contains>
 
-  my $success = $content->body_contains('1234567');
+  my $success = $single->body_contains('1234567');
 
 Check if content contains a specific string.
 
 =head2 C<body_size>
 
-  my $size = $content->body_size;
+  my $size = $single->body_size;
 
 Content size in bytes.
 
 =head2 C<clone>
 
-  my $clone = $content->clone;
+  my $clone = $single->clone;
 
 Clone content if possible.
 Note that this method is EXPERIMENTAL and might change without warning!
 
 =head2 C<get_body_chunk>
 
-  my $chunk = $content->get_body_chunk(0);
+  my $chunk = $single->get_body_chunk(0);
 
 Get a chunk of content starting from a specfic position.
 
 =head2 C<parse>
 
-  $content = $content->parse("Content-Length: 12\r\n\r\nHello World!");
+  $single = $single->parse("Content-Length: 12\r\n\r\nHello World!");
 
 Parse content chunk.
 

diff --git a/t/mojo/message.t b/t/mojo/message.t
@@ -645,13 +645,13 @@ $req = Mojo::Message::Request->new;
 my $stream = '';
 $req->content->on(
   body => sub {
-    my $content = shift;
-    $content->on(
+    my $single = shift;
+    $single->on(
       upgrade => sub {
-        my ($content, $multipart) = @_;
-        $multipart->on(
+        my ($single, $multi) = @_;
+        $multi->on(
           part => sub {
-            my ($multipart, $part) = @_;
+            my ($multi, $part) = @_;
             $part->on(
               body => sub {
                 my $part = shift;