Add more explanation to docs for request.finish().

doc/api.html

@@ -1319,18 +1319,42 @@ <h4 id="_tt_node_http_clientrequest_tt"><tt>node.http.ClientRequest</tt></h4>
 as it is faster.</p></div>
 </dd>
 <dt class="hdlist1">
-<tt>request.finish(response_listener)</tt> 
+<tt>request.finish(responseListener)</tt> 
 </dt>
 <dd>
 <p>
 Finishes sending the request. If any parts of the body are
 unsent, it will flush them to the socket. If the request is
 chunked, this will send the terminating <tt>"0\r\n\r\n"</tt>.
 </p>
-<div class="paragraph"><p>The parameter <tt>response_listener</tt> is a callback which
+<div class="paragraph"><p>The parameter <tt>responseListener</tt> is a callback which
 will be executed when the response headers have been received.
-The <tt>response_listener</tt> callback is executed with one
+The <tt>responseListener</tt> callback is executed with one
 argument which is an instance of <tt>node.http.ClientResponse</tt>.</p></div>
+<div class="paragraph"><p>In the <tt>responseListener</tt> callback, one can add more listeners to the
+response, in particular listening for the <tt>"body"</tt> event. Note that
+the <tt>responseListener</tt> is called before any part of the body is receieved,
+so there is no need to worry about racing to catch the first part of the
+body. As long as a listener for <tt>"body"</tt> is added during the
+<tt>responseListener</tt> callback, the entire body will be caught.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>// Good
+request.finish(function (response) {
+  response.addListener("body", function (chunk) {
+    puts("BODY: " + chunk);
+  });
+});
+
+// Bad - misses all or part of the body
+request.finish(function (response) {
+  setTimeout(function () {
+    response.addListener("body", function (chunk) {
+      puts("BODY: " + chunk);
+    });
+  }, 10);
+});</tt></pre>
+</div></div>
 </dd>
 </dl></div>
 <h4 id="_tt_node_http_clientresponse_tt"><tt>node.http.ClientResponse</tt></h4>
@@ -1906,7 +1930,7 @@ <h2 id="_extension_api">Extension API</h2>
 <div id="footer">
 <div id="footer-text">
 Version 0.1.10<br />
-Last updated 2009-09-15 22:34:24 CEST
+Last updated 2009-09-17 15:13:13 CEST
 </div>
 </div>
 </body>

doc/api.txt

@@ -845,16 +845,42 @@ argument should be either +"utf8"+ or
 as it is faster.
 
 
-+request.finish(response_listener)+ ::
++request.finish(responseListener)+ ::
 
 Finishes sending the request. If any parts of the body are
 unsent, it will flush them to the socket. If the request is
 chunked, this will send the terminating +"0\r\n\r\n"+.
 +
-The parameter +response_listener+ is a callback which
+The parameter +responseListener+ is a callback which
 will be executed when the response headers have been received.
-The +response_listener+ callback is executed with one
+The +responseListener+ callback is executed with one
 argument which is an instance of +node.http.ClientResponse+.
++
+In the +responseListener+ callback, one can add more listeners to the
+response, in particular listening for the +"body"+ event. Note that
+the +responseListener+ is called before any part of the body is receieved,
+so there is no need to worry about racing to catch the first part of the
+body. As long as a listener for +"body"+ is added during the
++responseListener+ callback, the entire body will be caught.
++
+----------------------------------------
+// Good
+request.finish(function (response) {
+  response.addListener("body", function (chunk) {
+    puts("BODY: " + chunk);
+  });
+});
+
+// Bad - misses all or part of the body
+request.finish(function (response) {
+  setTimeout(function () {
+    response.addListener("body", function (chunk) {
+      puts("BODY: " + chunk);
+    });
+  }, 10);
+});
+----------------------------------------
+
 
 
 

doc/node.1

@@ -1,11 +1,11 @@
 .\"     Title: node
 .\"    Author: 
 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
-.\"      Date: 09/15/2009
+.\"      Date: 09/17/2009
 .\"    Manual: 
 .\"    Source: 
 .\"
-.TH "NODE" "1" "09/15/2009" "" ""
+.TH "NODE" "1" "09/17/2009" "" ""
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@@ -1226,17 +1226,49 @@ or
 "ascii"\. By default the body uses ASCII encoding, as it is faster\.
 .RE
 .PP
-request\.finish(response_listener)
+request\.finish(responseListener)
 .RS 4
 Finishes sending the request\. If any parts of the body are unsent, it will flush them to the socket\. If the request is chunked, this will send the terminating
 "0\er\en\er\en"\.
 .sp
 The parameter
-response_listener
+responseListener
 is a callback which will be executed when the response headers have been received\. The
-response_listener
+responseListener
 callback is executed with one argument which is an instance of
 node\.http\.ClientResponse\.
+.sp
+In the
+responseListener
+callback, one can add more listeners to the response, in particular listening for the
+"body"
+event\. Note that the
+responseListener
+is called before any part of the body is receieved, so there is no need to worry about racing to catch the first part of the body\. As long as a listener for
+"body"
+is added during the
+responseListener
+callback, the entire body will be caught\.
+.sp
+.RS 4
+.nf
+// Good
+request\.finish(function (response) {
+  response\.addListener("body", function (chunk) {
+    puts("BODY: " + chunk);
+  });
+});
+
+// Bad \- misses all or part of the body
+request\.finish(function (response) {
+  setTimeout(function () {
+    response\.addListener("body", function (chunk) {
+      puts("BODY: " + chunk);
+    });
+  }, 10);
+});
+.fi
+.RE
 .RE
 .RE
 .sp