Clean up documentation and formatting in RKParamsAttachment header.

* Add documentation to overview.
* Clean up asterisk placements in variable declarations.
* Add appledoc section headers.
* Reorganize methods and properties for documentation clarity.
* Fill in missing documentation, parameter definitions, and return values.
* Clean up whitespace inconsistencies.

Code/Network/RKParamsAttachment.h

@@ -21,29 +21,74 @@
 #import <Foundation/Foundation.h>
 
 /**
- Models an individual part of a multi-part MIME document. These
- attachments are stacked together within the RKParams document to
- allow for uploading files via HTTP
+ Models an individual part of a multi-part MIME document. These attachments are
+ stacked together within the RKParams document to allow for uploading files via
+ HTTP.
+ 
+ Typically, interactions with the RKParamsAttachment are accomplished through
+ the RKParams class and there shouldn't be much need to deal directly with this
+ class.
  */
 @interface RKParamsAttachment : NSObject {
-	NSString *_name;
+    NSString *_name;
     NSString *_fileName;    
-	NSString *_MIMEType;
+    NSString *_MIMEType;
 
 	@private
-    NSString        *_filePath;
-    NSData          *_body;
-    NSInputStream   *_bodyStream;
-	NSData          *_MIMEHeader;
-	NSUInteger		_MIMEHeaderLength;	
-	NSUInteger		_bodyLength;
-	NSUInteger		_length;
-	NSUInteger		_delivered;
-    id<NSObject>    _value;
+    NSString *_filePath;
+    NSData *_body;
+    NSInputStream *_bodyStream;
+    NSData *_MIMEHeader;
+    NSUInteger _MIMEHeaderLength;	
+    NSUInteger _bodyLength;
+    NSUInteger _length;
+    NSUInteger _delivered;
+    id<NSObject> _value;
 }
 
+
+///-----------------------------------------------------------------------------
+/// @name Creating an Attachment
+///-----------------------------------------------------------------------------
+
 /**
- The parameter name of this attachment in the multi-part document
+ Returns a newly initialized attachment with a given parameter name and value.
+ 
+ @param name The parameter name of this attachment in the multi-part document.
+ @param value A value that is used to create the attachment body
+ @return An initialized attachment with the given name and value.
+ */
+- (id)initWithName:(NSString *)name value:(id<NSObject>)value;
+
+/**
+ Returns a newly initialized attachment with a given parameter name and the data
+ stored in an NSData object.
+ 
+ @param name The parameter name of this attachment in the multi-part document.
+ @param data The data that is used to create the attachment body.
+ @return An initialized attachment with the given name and data.
+ */
+- (id)initWithName:(NSString *)name data:(NSData *)data;
+
+/**
+ Returns a newly initialized attachment with a given parameter name and the data
+ stored on disk at the given file path.
+ 
+ @param name The parameter name of this attachment in the multi-part document.
+ @param filePath The complete path of a file to use its data contents as the
+ attachment body.
+ @return An initialized attachment with the name and the contents of the file at
+ the path given.
+ */
+- (id)initWithName:(NSString *)name file:(NSString *)filePath;
+
+
+///-----------------------------------------------------------------------------
+/// @name Working with the Attachment
+///-----------------------------------------------------------------------------
+
+/**
+ The parameter name of this attachment in the multi-part document.
  */
 @property (nonatomic, retain) NSString *name;
 
@@ -51,7 +96,7 @@
  The MIME type of the attached file in the MIME stream. MIME Type will be
  auto-detected from the file extension of the attached file.
  
- Defaults to nil
+ **Default**: nil
  */
 @property (nonatomic, retain) NSString *MIMEType;
 
@@ -67,49 +112,54 @@
 
 /**
  The name of the attached file in the MIME stream
- Defaults to the name of the file attached or nil if there is not one.
+ 
+ **Default**: The name of the file attached or nil if there is not one.
  */
 @property (nonatomic, retain) NSString *fileName;
 
-// this value is set iff the object is init through initWithName:value
+/**
+ The value that is set when initialized through initWithName:value:
+ */
 @property (nonatomic, retain) id<NSObject> value;
 
 /**
- Initialize a new attachment with a given parameter name and a value
- */
-- (id)initWithName:(NSString *)name value:(id<NSObject>)value;
-
-/**
- Initialize a new attachment with a given parameter name and the data stored in an NSData object
- */
-- (id)initWithName:(NSString *)name data:(NSData *)data;
-
-/**
- Initialize a new attachment with a given parameter name and the data stored on disk at the given file path
- */
-- (id)initWithName:(NSString *)name file:(NSString *)filePath;
-
-/**
- Open the attachment stream to begin reading. This will generate a MIME header and prepare the
- attachment for writing to an RKParams stream
+ Open the attachment stream to begin reading. This will generate a MIME header
+ and prepare the attachment for writing to an RKParams stream.
  */
 - (void)open;
 
 /**
- The length of the entire attachment (including the MIME Header and the body)
+ The length of the entire attachment including the MIME header and the body.
+ 
+ @return Unsigned integer of the MIME header and the body.
  */
 - (NSUInteger)length;
 
 /**
- Read the attachment body in a streaming fashion
- */
-- (NSUInteger)read:(uint8_t *)buffer maxLength:(NSUInteger)len;
-
-/**
- Calculate and return an MD5 checksum for the body of this attachment. This works
- for simple values, NSData structures in memory, or by efficiently streaming a file
- and calculating an MD5.
+ Calculate and return an MD5 checksum for the body of this attachment.
+ 
+ This works for simple values, NSData structures in memory, or by efficiently
+ streaming a file and calculating an MD5.
  */
 - (NSString *)MD5;
 
+
+///-----------------------------------------------------------------------------
+/// @name Input streaming
+///-----------------------------------------------------------------------------
+
+/**
+ Read the attachment body in a streaming fashion for NSInputStream.
+ 
+ @param buffer A data buffer. The buffer must be large enough to contain the
+ number of bytes specified by len.
+ @param len The maximum number of bytes to read.
+ @return A number indicating the outcome of the operation:
+ 
+ - A positive number indicates the number of bytes read;
+ - 0 indicates that the end of the buffer was reached;
+ - A negative number means that the operation failed.
+ */
+- (NSUInteger)read:(uint8_t *)buffer maxLength:(NSUInteger)len;
+
 @end