Fixing up documentation; Still need to figure out how to properly

document enums, typedefs in Doxygen

Classes/NSBundle+YAJL.h

@@ -29,12 +29,19 @@
 
 #import "YAJLParser.h"
 
-@interface NSBundle (YAJL)
+/*!
+ Utilities for loading JSON from resource bundles.
+ 
+ @code
+ id JSONValue = [[NSBundle mainBundle] yajl_JSONFromResource:@"kegs.json"];
+ @endcode
+ */
+@interface NSBundle(YAJL)
 
 /*!
- Load JSON from bundle. 
- Throws an YAJLParserException on parse error.
+ Load JSON from bundle.  
  @param resource Resource name with extension, for example, file.json
+ @throws YAJLParserException On parse error
  */
 - (id)yajl_JSONFromResource:(NSString *)resource;
 

Classes/NSBundle+YAJL.m

@@ -31,7 +31,7 @@
 #import "GHNSBundle+Utils.h"
 #import "NSObject+YAJL.h"
 
-@implementation NSBundle (YAJL)
+@implementation NSBundle(YAJL)
 
 - (id)yajl_JSONFromResource:(NSString *)resource {
   NSError *error = nil;

Classes/NSObject+YAJL.h

@@ -30,15 +30,41 @@
 #import "YAJLGen.h"
 #import "YAJLParser.h"
 
-@interface NSObject (YAJL)
+/*!
+ Generate JSON string from NSArray, NSDictionary or custom object or parse JSON from NSString or custom object.
+ 
+ Parse JSON:
+ @code
+ NSData *JSONData = [NSData dataWithContentsOfFile:@"example.json"];
+ NSArray *arrayFromData = [JSONData yajl_JSON];
+ 
+ NSString *JSONString = @"[\"Test\"]";
+ NSArray *arrayFromString = [JSONString yajl_JSON];
+ 
+ // With options and out error
+ NSError *error = nil;
+ NSArray *arrayFromString = [JSONString yajl_JSONWithOptions:YAJLParserOptionsAllowComments error:&error];
+ @endcode
+ 
+ Generate JSON:
+ @code
+ NSDictionary *dict = [NSDictionary dictionaryWithObject:@"value" forKey:@"key"];
+ NSString *JSONString = [dict yajl_JSONString];
+ 
+ // Beautified with custon indent string
+ NSArray *array = [NSArray arrayWithObjects:@"value1", @"value2", nil];
+ NSString *JSONString = [dict yajl_JSONStringWithOptions:YAJLGenOptionsBeautify indentString:@"    "];
+ @endcode
+ */
+@interface NSObject(YAJL)
 
 #pragma mark Gen
 
 /*!
  Create JSON string from object.
  Supported objects include: NSArray, NSDictionary, NSNumber, NSString, NSNull
  To override JSON value to encode (or support custom objects), implement (id)JSON; See YAJLCoding in YAJLGen.h
- Otherwise throws YAJLGenInvalidObjectException.
+ @throws YAJLGenInvalidObjectException If object is invalid
  @result JSON String
  */
 - (NSString *)yajl_JSONString;
@@ -47,7 +73,7 @@
  Create JSON string from object.
  Supported objects include: NSArray, NSDictionary, NSNumber, NSString, NSNull
  To override JSON value to encode (or support custom objects), implement (id)JSON; See YAJLCoding in YAJLGen.h
- Otherwise throws YAJLGenInvalidObjectException.
+ @throws YAJLGenInvalidObjectException If object is invalid
  @param options
  @param indentString
  @result JSON String

Classes/NSObject+YAJL.m

@@ -31,7 +31,7 @@
 #import "YAJLGen.h"
 #import "YAJLDocument.h"
 
-@implementation NSObject (YAJL)
+@implementation NSObject(YAJL)
 
 #pragma mark Gen
 

Classes/YAJLDocument.h

@@ -40,14 +40,76 @@ extern NSInteger YAJLDocumentStackCapacity;
 
 @class YAJLDocument;
 
+/*!
+ YAJLDocument delegate notified when objects are added.
+ */
 @protocol YAJLDocumentDelegate <NSObject>
 @optional
+/*!
+ Did add dictionary.
+ @param document Sender
+ @param dict Dictionary that was added
+ */
 - (void)document:(YAJLDocument *)document didAddDictionary:(NSDictionary *)dict;
+
+/*!
+ Did add array.
+ @param document Sender
+ @param array Array that was added
+ */
 - (void)document:(YAJLDocument *)document didAddArray:(NSArray *)array;
+
+/*!
+ Did add object to array.
+ @param document Sender
+ @param object Object added
+ @param array Array objct was added to
+ */
 - (void)document:(YAJLDocument *)document didAddObject:(id)object toArray:(NSArray *)array;
+
+/*!
+ Did set object for key on dictionary.
+ @param document Sender
+ @param object Object that was set
+ @param key Key
+ @param dict Dictionary object was set for key on
+ */
 - (void)document:(YAJLDocument *)document didSetObject:(id)object forKey:(id)key inDictionary:(NSDictionary *)dict;
 @end
 
+/*!
+ JSON document interface.
+ 
+ @code
+ NSData *data = [NSData dataWithContentsOfFile:@"example.json"];
+ NSError *error = nil;
+ YAJLDocument *document = [[YAJLDocument alloc] initWithData:data parserOptions:YAJLParserOptionsNone error:&error];
+ // Access root element at document.root
+ NSLog(@"Root: %@", document.root);
+ [document release];
+ @endcode
+ 
+ Example for streaming:
+ @code
+ YAJLDocument *document = [[YAJLDocument alloc] init];
+ document.delegate = self;
+ 
+ NSError *error = nil;
+ [document parse:chunk1 error:error];
+ [document parse:chunk2 error:error];
+ 
+ // You can access root element at document.root
+ NSLog(@"Root: %@", document.root);
+ [document release];
+ 
+ // Or via the YAJLDocumentDelegate delegate methods
+ 
+ - (void)document:(YAJLDocument *)document didAddDictionary:(NSDictionary *)dict { }
+ - (void)document:(YAJLDocument *)document didAddArray:(NSArray *)array { }
+ - (void)document:(YAJLDocument *)document didAddObject:(id)object toArray:(NSArray *)array { }
+ - (void)document:(YAJLDocument *)document didSetObject:(id)object forKey:(id)key inDictionary:(NSDictionary *)dict { }
+ @endcode
+ */
 @interface YAJLDocument : NSObject <YAJLParserDelegate> {
 
   id root_; // NSArray or NSDictionary
@@ -69,9 +131,9 @@ extern NSInteger YAJLDocumentStackCapacity;
 
 }
 
-@property (readonly, nonatomic) id root; //! Root element
-@property (readonly, nonatomic) YAJLParserStatus parserStatus;
-@property (assign, nonatomic) id<YAJLDocumentDelegate> delegate;
+@property (readonly, nonatomic) id root; //! The root element of the document, either NSArray or NSDictionary
+@property (readonly, nonatomic) YAJLParserStatus parserStatus; //! The current status of parsing
+@property (assign, nonatomic) id<YAJLDocumentDelegate> delegate; //! Delegate
 
 /*!
  Create document from data.
@@ -90,7 +152,7 @@ extern NSInteger YAJLDocumentStackCapacity;
 /*!
  Parse data.
  @param data Data to parse
- @param error Error to set on failure
+ @param error Out error to set on failure
  @result Parser status
  */
 - (YAJLParserStatus)parse:(NSData *)data error:(NSError **)error;

Classes/YAJLGen.h

@@ -29,19 +29,19 @@
 
 #include "yajl_gen.h"
 
+//! Exception type if we encounter invalid object
 extern NSString *const YAJLGenInvalidObjectException;
 
 /*!
- @enum Generate options
- @constant YAJLGenOptionsBeautify
+ JSON generate options.
  */
 enum {
   YAJLGenOptionsNone = 0, 
-  YAJLGenOptionsBeautify = 1 << 0,
+  YAJLGenOptionsBeautify = 1 << 0, //! Beautifiy JSON output
   YAJLGenOptionsIgnoreUnknownTypes = 1 << 1, // Ignore unknown types (will use null value)
   YAJLGenOptionsIncludeUnsupportedTypes = 1 << 2, // Handle non-JSON types (including NSDate, NSData, NSURL)
 };
-typedef NSUInteger YAJLGenOptions;
+typedef NSUInteger YAJLGenOptions; //! JSON generate options.
 
 /*!
  YAJL JSON string generator.
@@ -54,44 +54,108 @@ typedef NSUInteger YAJLGenOptions;
  
  We also support the following types (if using YAJLGenOptionsIncludeUnsupportedTypes option),
  by converting to JSON supported types:
- - NSDate -> number representing number of milliseconds since (1970) epoch
- - NSData -> Base64 encoded string
- - NSURL -> URL (absolute) string 
+ - NSDate: number representing number of milliseconds since (1970) epoch
+ - NSData: Base64 encoded string
+ - NSURL: URL (absolute) string 
  */
 @interface YAJLGen : NSObject {
   yajl_gen gen_;
 
   YAJLGenOptions genOptions_;
 }
 
+/*!
+ JSON generator with options.
+ @param genOptions Generate options
+ @param indentString String for indentation
+ */
 - (id)initWithGenOptions:(YAJLGenOptions)genOptions indentString:(NSString *)indentString;
 
+/*!
+ Write JSON for object to buffer.
+ @param obj Supported or custom object
+ */
 - (void)object:(id)obj;
 
+/*!
+ Write null value to buffer.
+ */
 - (void)null;
 
+/*!
+ Write bool value to buffer.
+ @param b Output true or false
+ */
 - (void)bool:(BOOL)b;
 
+/*!
+ Write numeric value to buffer.
+ @param number Numeric value
+ */
 - (void)number:(NSNumber *)number;
 
+/*!
+ Write string value to buffer.
+ @param s String value
+ */
 - (void)string:(NSString *)s;
 
+/*!
+ Write dictionary start ('{') to buffer.
+ */
 - (void)startDictionary;
+
+/*!
+ Write dictionary end ('}') to buffer.
+ */
 - (void)endDictionary;
 
+/*!
+ Write array start ('[') to buffer.
+ */
 - (void)startArray;
 
+/*!
+ Write array end (']') to buffer.
+ */
 - (void)endArray;
 
+/*!
+ Clear JSON buffer.
+ */
 - (void)clear;
 
+/*!
+ Get current JSON buffer.
+ */
 - (NSString *)buffer;
 
 @end
 
 
 /*!
  Custom objects can support manual JSON encoding.
+ 
+ @code
+ @interface CustomObject : NSObject
+ @end
+ 
+ @implementation CustomObject
+ 
+ - (id)JSON {
+ return [NSArray arrayWithObject:[NSNumber numberWithInteger:1]];
+ }
+ 
+ @end
+ @endcode
+ 
+ And then:
+ 
+ @code 
+ CustomObject *customObject = [[CustomObject alloc] init];
+ NSString *JSONString = [customObject yajl_JSON];
+ // JSONString == "[1]";
+ @endcode
  */
 @protocol YAJLCoding <NSObject>