update form documentation for new usage

README.md

@@ -215,6 +215,8 @@ request.get('unix://tmp/unix.socket/httppath')
 
 `request` supports `application/x-www-form-urlencoded` and `multipart/form-data` form uploads. For `multipart/related` refer to the `multipart` API.
 
+#### application/x-www-form-urlencoded (URL-Encoded Forms)
+
 URL-encoded forms are simple.
 
 ```javascript
@@ -225,22 +227,28 @@ request.post('http://service.com/upload').form({key:'value'})
 request.post({url:'http://service.com/upload', form: {key:'value'}}, function(err,httpResponse,body){ /* ... */ })
 ```
 
-For `multipart/form-data` we use the [form-data](https://github.com/felixge/node-form-data) library by [@felixge](https://github.com/felixge). For the most basic case, you can pass your upload form data via the `formData` option.
+#### multipart/form-data (Multipart Form Uploads)
+
+For `multipart/form-data` we use the [form-data](https://github.com/felixge/node-form-data) library by [@felixge](https://github.com/felixge). For the most cases, you can pass your upload form data via the `formData` option.
 
 
 ```javascript
 var formData = {
+  // Pass a simple key-value pair
   my_field: 'my_value',
+  // Pass data via Buffers
   my_buffer: new Buffer([1, 2, 3]),
+  // Pass data via Streams
   my_file: fs.createReadStream(__dirname + '/unicycle.jpg'),
-  remote_file: request(remoteFile),
+  // Pass multiple values /w an Array
   attachments: [
     fs.createReadStream(__dirname + '/attacment1.jpg')
     fs.createReadStream(__dirname + '/attachment2.jpg')
   ],
+  // Pass optional meta-data with an 'options' object with style: {value: DATA, options: OPTIONS}
+  // See the `form-data` README for more information about options: https://github.com/felixge/node-form-data
   custom_file: {
     value:  fs.createReadStream('/dev/urandom'),
-    // See the [form-data](https://github.com/felixge/node-form-data) README for more information about options.
     options: {
       filename: 'topsecret.jpg',
       contentType: 'image/jpg'
@@ -255,24 +263,20 @@ request.post({url:'http://service.com/upload', formData: formData}, function opt
 });
 ```
 
-For more advanced cases (like appending form data options) you'll need access to the form itself.
+For advanced cases, you can the form-data object itself via `r.form()`. This can be modified until the request is fired on the next cycle of the event-loop. (Note that this calling `form()` will clear the currently set form data for that request.)
 
 ```javascript
-var r = request.post('http://service.com/upload', function optionalCallback(err, httpResponse, body) {
-  if (err) {
-    return console.error('upload failed:', err);
-  }
-  console.log('Upload successful!  Server responded with:', body);
-})
+// NOTE: Advanced use-case, for normal use see 'formData' usage above
+var r = request.post('http://service.com/upload', function optionalCallback(err, httpResponse, body) { // ...
 
-// Just like always, `r` is a writable stream, and can be used as such (you have until nextTick to pipe it, etc.)
-// Alternatively, you can provide a callback (that's what this example does — see `optionalCallback` above).
 var form = r.form();
 form.append('my_field', 'my_value');
 form.append('my_buffer', new Buffer([1, 2, 3]));
-form.append('my_buffer', fs.createReadStream(__dirname + '/unicycle.jpg'), {filename: 'unicycle.jpg'});
+form.append('custom_file', fs.createReadStream(__dirname + '/unicycle.jpg'), {filename: 'unicycle.jpg'});
 ```
-See the [form-data](https://github.com/felixge/node-form-data) README for more information & examples.
+See the [form-data README](https://github.com/felixge/node-form-data) for more information & examples.
+
+#### multipart/related
 
 Some variations in different HTTP implementations require a newline/CRLF before, after, or both before and after the boundary of a `multipart/form-data` request. This has been observed in the .NET WebAPI version 4.0. You can turn on a boundary preambleCRLF or postamble by passing them as `true` to your request options.
 
@@ -431,7 +435,9 @@ The first argument can be either a `url` or an `options` object. The only requir
 * `method` - http method (default: `"GET"`)
 * `headers` - http headers (default: `{}`)
 * `body` - entity body for PATCH, POST and PUT requests. Must be a `Buffer` or `String`, unless `json` is `true`. If `json` is `true`, then `body` must be a JSON-serializable object.
-* `form` - when passed an object or a querystring, this sets `body` to a querystring representation of value, and adds `Content-type: application/x-www-form-urlencoded` header. When passed no options, a `FormData` instance is returned (and is piped to request).
+* `form` - when passed an object or a querystring, this sets `body` to a querystring representation of value, and adds `Content-type: application/x-www-form-urlencoded` header. When passed no options, a `FormData` instance is returned (and is piped to request). See "Forms" section above.
+* `formData` - Data to pass for a `multipart/form-data` request. See "Forms" section above.
+* `multipart` - (experimental) Data to pass for a `multipart/related` request. See "Forms" section above
 * `auth` - A hash containing values `user` || `username`, `pass` || `password`, and `sendImmediately` (optional).  See documentation above.
 * `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header.  Additionally, parses the response body as JSON.
 * `multipart` - (experimental) array of objects which contains their own headers and `body` attribute. Sends `multipart/related` request. See example below.