Clean up documentation and formatting in RKRequestSerializable header.

* Reorganize documentation to be included in overview.
* Clean up asterisk placements in declarations.
* Add appledoc section headers.
* Fill in missing documentation, parameter definitions, and return values.
* Clean up whitespace inconsistencies.

Code/Network/RKRequestSerializable.h

@@ -18,48 +18,76 @@
 //  limitations under the License.
 //
 
-/*
- * This protocol is implemented by objects that can be serialized into a representation suitable
- * for transmission over a REST request. Suitable serializations are x-www-form-urlencoded and
- * multipart/form-data.
+/**
+ This protocol is implemented by objects that can be serialized into a
+ representation suitable for transmission over a REST request. Suitable
+ serializations are x-www-form-urlencoded and multipart/form-data.
+ 
+ @warning One of the following methods MUST be implemented for your serializable
+ implementation to be complete:
+ 
+ - (NSData *)HTTPBody - If you are allowing serialization of a small in-memory
+ data structure, implement HTTPBody as it is much simpler.
+ - (NSInputStream *)HTTPBodyStream - This provides support for streaming a large
+ payload from disk instead of memory.
+
  */
 @protocol RKRequestSerializable
 
+///-----------------------------------------------------------------------------
+/// @name HTTP Headers
+///-----------------------------------------------------------------------------
+
 /**
- * The value of the Content-Type header for the HTTP Body representation of the serialization
+ The value of the Content-Type header for the HTTP Body representation of the
+ serialization.
+ 
+ @return A string value of the Content-Type header for the HTTP body.
  */
-- (NSString*)HTTPHeaderValueForContentType;
+- (NSString *)HTTPHeaderValueForContentType;
 
 @optional
 
-/**
- * NOTE: One of the following methods MUST be implemented for your serializable implementation
- * to be complete. If you are allowing serialization of a small in-memory data structure, implement
- * HTTPBody as it is much simpler. HTTPBodyStream provides support for streaming a large payload
- * from disk instead of memory.
- */
+///-----------------------------------------------------------------------------
+/// @name Body Implementation
+///-----------------------------------------------------------------------------
 
 /**
- * An NSData representing the HTTP Body serialization of the object implementing the protocol
+ An NSData representing the HTTP Body serialization of the object implementing
+ the protocol.
+ 
+ @return An NSData object respresenting the HTTP body serialization.
  */
-- (NSData*)HTTPBody;
+- (NSData *)HTTPBody;
 
 /**
- * Returns an input stream for reading the serialization as a stream. Used to provide support for
- * handling large HTTP payloads.
+ Returns an input stream for reading the serialization as a stream used to
+ provide support for handling large HTTP payloads.
+ 
+ @return An input stream for reading the serialization as a stream.
  */
-- (NSInputStream*)HTTPBodyStream;
+- (NSInputStream *)HTTPBodyStream;
+
+
+///-----------------------------------------------------------------------------
+/// @name Optional HTTP Headers
+///-----------------------------------------------------------------------------
 
 /**
- * Returns the length of the HTTP Content-Length header
+ Returns the length of the HTTP Content-Length header.
+ 
+ @return Unsigned integer length of the HTTP Content-Length header.
  */
 - (NSUInteger)HTTPHeaderValueForContentLength;
 
 /**
- * The value of the Content-Type header for the HTTP Body representation of the serialization
- *
- * @deprecated Implement HTTPHeaderValueForContentType instead
+ The value of the Content-Type header for the HTTP Body representation of the
+ serialization.
+ 
+ @bug **DEPRECATED** in v0.9.4: Implement [RKRequestSerializable HTTPHeaderValueForContentType]
+ instead.
+ @return A string value of the Content-Type header for the HTTP body.
  */
-- (NSString*)ContentTypeHTTPHeader DEPRECATED_ATTRIBUTE;
+- (NSString *)ContentTypeHTTPHeader DEPRECATED_ATTRIBUTE;
 
 @end