Added lots of comments

Added missing setDownloadProgressDelegate to ASIHTTPRequest

@@ -10,20 +10,20 @@
 
 
 @interface ASIFormDataRequest : ASIHTTPRequest {
 @interface ASIFormDataRequest : ASIHTTPRequest {
 
 
-	//Parameters that will be POSTed to the url
+	// Parameters that will be POSTed to the url
 	NSMutableDictionary *postData;
 	NSMutableDictionary *postData;
 	
 	
-	//Files that will be POSTed to the url
+	// Files that will be POSTed to the url
 	NSMutableDictionary *fileData;
 	NSMutableDictionary *fileData;
 	
 	
 }
 }
 
 
 #pragma mark setup request
 #pragma mark setup request
 
 
-//Add a POST variable to the request
+// Add a POST variable to the request
 - (void)setPostValue:(id)value forKey:(NSString *)key;
 - (void)setPostValue:(id)value forKey:(NSString *)key;
 
 
-//Add the contents of a local file as a POST variable to the request
+// Add the contents of a local file as a POST variable to the request
 - (void)setFile:(NSString *)filePath forKey:(NSString *)key;
 - (void)setFile:(NSString *)filePath forKey:(NSString *)key;
 
 
 @end
 @end

@@ -61,11 +61,11 @@
 
 
 	NSMutableData *body = [[[NSMutableData alloc] init] autorelease];
 	NSMutableData *body = [[[NSMutableData alloc] init] autorelease];
 	
 	
-	//Set your own boundary string only if really obsessive. We don't bother to check if post data contains the boundary, since it's pretty unlikely that it does.
+	// Set your own boundary string only if really obsessive. We don't bother to check if post data contains the boundary, since it's pretty unlikely that it does.
 	NSString *stringBoundary = @"0xKhTmLbOuNdArY";
 	NSString *stringBoundary = @"0xKhTmLbOuNdArY";
 	
 	
 	if ([fileData count] > 0) {
 	if ([fileData count] > 0) {
-		//We need to use multipart/form-data when using file upload
+		// We need to use multipart/form-data when using file upload
 		[self addRequestHeader:@"Content-Type" value:[NSString stringWithFormat:@"multipart/form-data; boundary=%@",stringBoundary]];
 		[self addRequestHeader:@"Content-Type" value:[NSString stringWithFormat:@"multipart/form-data; boundary=%@",stringBoundary]];
 	}
 	}
 	
 	
@@ -73,7 +73,7 @@
 	
 	
 	[body appendData:[[NSString stringWithFormat:@"--%@\r\n",stringBoundary] dataUsingEncoding:NSUTF8StringEncoding]];
 	[body appendData:[[NSString stringWithFormat:@"--%@\r\n",stringBoundary] dataUsingEncoding:NSUTF8StringEncoding]];
 	
 	
-	//Adds post data
+	// Adds post data
 	NSData *endItemBoundary = [[NSString stringWithFormat:@"\r\n--%@\r\n",stringBoundary] dataUsingEncoding:NSUTF8StringEncoding];
 	NSData *endItemBoundary = [[NSString stringWithFormat:@"\r\n--%@\r\n",stringBoundary] dataUsingEncoding:NSUTF8StringEncoding];
 	NSEnumerator *e = [postData keyEnumerator];
 	NSEnumerator *e = [postData keyEnumerator];
 	NSString *key;
 	NSString *key;
@@ -87,7 +87,7 @@
 		}
 		}
 	}
 	}
 	
 	
-	//Adds files to upload
+	// Adds files to upload
 	NSData *contentTypeHeader = [[NSString stringWithString:@"Content-Type: application/octet-stream\r\n\r\n"] dataUsingEncoding:NSUTF8StringEncoding];
 	NSData *contentTypeHeader = [[NSString stringWithString:@"Content-Type: application/octet-stream\r\n\r\n"] dataUsingEncoding:NSUTF8StringEncoding];
 	e = [fileData keyEnumerator];
 	e = [fileData keyEnumerator];
 	i=0;
 	i=0;
@@ -97,14 +97,14 @@
 		[body appendData:contentTypeHeader];
 		[body appendData:contentTypeHeader];
 		[body appendData:[NSData dataWithContentsOfMappedFile:filePath]];
 		[body appendData:[NSData dataWithContentsOfMappedFile:filePath]];
 		i++;
 		i++;
-		if (i != [fileData count]) { //Only add the boundary if this is not the last item in the post body
+		// Only add the boundary if this is not the last item in the post body
+		if (i != [fileData count]) { 
 			[body appendData:endItemBoundary];
 			[body appendData:endItemBoundary];
 		}
 		}
 	}
 	}
 	
 	
 	[body appendData:[[NSString stringWithFormat:@"\r\n--%@--\r\n",stringBoundary] dataUsingEncoding:NSUTF8StringEncoding]];
 	[body appendData:[[NSString stringWithFormat:@"\r\n--%@--\r\n",stringBoundary] dataUsingEncoding:NSUTF8StringEncoding]];
 
 
-	//Since we've got post data, let's set the post body to an empty NSMutableData object
 	[self setPostBody:body];
 	[self setPostBody:body];
 	
 	
 	//Now we've created our post data, construct the request
 	//Now we've created our post data, construct the request

@@ -163,8 +163,13 @@
 - (void)updateUploadProgress;
 - (void)updateUploadProgress;
 - (void)resetDownloadProgress:(NSNumber *)max;
 - (void)resetDownloadProgress:(NSNumber *)max;
 - (void)updateDownloadProgress;
 - (void)updateDownloadProgress;
+
+// Called when authorisation is needed, as we only find out we don't have permission to something when the upload is complete
 - (void)removeUploadProgressSoFar;
 - (void)removeUploadProgressSoFar;
 
 
+// Helper method for interacting with progress indicators to abstract the details of different APIS (NSProgressIndicator and UIProgressView)
++ (void)setProgress:(double)progress forProgressIndicator:(id)indicator;
+
 #pragma mark handling request complete / failure
 #pragma mark handling request complete / failure
 
 
 // Called when a request completes successfully - defaults to: @selector(requestFinished:)
 // Called when a request completes successfully - defaults to: @selector(requestFinished:)
@@ -228,8 +233,6 @@
 // Dump all session data (authentication and cookies)
 // Dump all session data (authentication and cookies)
 + (void)clearSession;
 + (void)clearSession;
 
 
-//Helper method for interacting with progress indicators to abstract the details of different APIS for cocoa and cocoa touch
-+ (void)setProgress:(double)progress forProgressIndicator:(id)indicator;
 
 
 @property (retain) NSString *username;
 @property (retain) NSString *username;
 @property (retain) NSString *password;
 @property (retain) NSString *password;

@@ -20,7 +20,6 @@
 - (void)testFileDownload;
 - (void)testFileDownload;
 - (void)testDownloadProgress;
 - (void)testDownloadProgress;
 - (void)testUploadProgress;
 - (void)testUploadProgress;
-- (void)testOperationQueue;
 - (void)testCookies;
 - (void)testCookies;
 
 
 @end
 @end

@@ -141,66 +141,6 @@ More tests needed for:
  
  
 
 
 
 
-- (void)testOperationQueue
-{
-	NSOperationQueue *queue = [[[NSOperationQueue alloc] init] autorelease];
-
-	NSURL *url;	
-	url = [[[NSURL alloc] initWithString:@"http://allseeing-i.com/asi-http-request/tests/first"] autorelease];
-	ASIHTTPRequest *request1 = [[[ASIHTTPRequest alloc] initWithURL:url] autorelease];
-	[queue addOperation:request1];
-
-	url = [[[NSURL alloc] initWithString:@"http://allseeing-i.com/asi-http-request/tests/second"] autorelease];
-	ASIHTTPRequest *request2 = [[[ASIHTTPRequest alloc] initWithURL:url] autorelease];
-	[queue addOperation:request2];
-
-	url = [[[NSURL alloc] initWithString:@"http://allseeing-i.com/asi-http-request/tests/third"] autorelease];
-	ASIHTTPRequest *request3 = [[[ASIHTTPRequest alloc] initWithURL:url] autorelease];
-	[queue addOperation:request3];
-	
-	url = [[[NSURL alloc] initWithString:@""] autorelease];
-	ASIHTTPRequest *request4 = [[[ASIHTTPRequest alloc] initWithURL:url] autorelease];
-	[queue addOperation:request4];
-	
-	url = [[[NSURL alloc] initWithString:@"http://allseeing-i.com/asi-http-request/tests/broken"] autorelease];
-	ASIHTTPRequest *request5 = [[[ASIHTTPRequest alloc] initWithURL:url] autorelease];
-	[queue addOperation:request5];
-
-	[queue waitUntilAllOperationsAreFinished];
-
-	BOOL success;
-
-	success = ([request1 error] == nil);
-	STAssertTrue(success,@"Request 1 failed");
-
-	success = [[request1 dataString] isEqualToString:@"This is the expected content for the first string"];
-	STAssertTrue(success,@"Failed to download the correct data for request 1");
-
-	success = ([request2 error] == nil);
-	STAssertTrue(success,@"Request 2 failed");
-
-	success = [[request2 dataString] isEqualToString:@"This is the expected content for the second string"];
-	STAssertTrue(success,@"Failed to download the correct data for request 2");
-
-	success = ([request3 error] == nil);
-	STAssertTrue(success,@"Request 3 failed");
-
-	success = [[request3 dataString] isEqualToString:@"This is the expected content for the third string"];
-	STAssertTrue(success,@"Failed to download the correct data for request 3");
-	
-	success = ([request4 error] != nil);
-	STAssertTrue(success,@"Request 4 succeed when it should have failed");
-
-	success = ([request5 error] == nil);
-	STAssertTrue(success,@"Request 5 failed");
-	
-	success = ([request5 responseStatusCode] == 404);
-	STAssertTrue(success,@"Failed to obtain the correct status code for request 5");
-		
-}
- 
-
-
 - (void)testCookies
 - (void)testCookies
 {
 {
 	BOOL success;
 	BOOL success;

@@ -9,27 +9,44 @@
 
 
 
 
 @interface ASINetworkQueue : NSOperationQueue {
 @interface ASINetworkQueue : NSOperationQueue {
+	
+	// Delegate will get didFail + didFinish messages (if set), as well as authorizationNeededForRequest messages
 	id delegate;
 	id delegate;
 
 
+	// Will be called when a request completes with the request as the argument
+	SEL requestDidFinishSelector;
+	
+	// Will be called when a request fails with the request as the argument
+	SEL requestDidFailSelector;
+	
+	// Will be called when the queue finishes with the queue as the argument
+	SEL queueDidFinishSelector;
+	
+	// Upload progress indicator, probably an NSProgressIndicator or UIProgressView
 	id uploadProgressDelegate;
 	id uploadProgressDelegate;
+	
+	// Total amount uploaded so far for all requests in this queue
 	int uploadProgressBytes;
 	int uploadProgressBytes;
+	
+	// Total amount to be uploaded for all requests in this queue - requests add to this figure as they work out how much data they have to transmit
 	int uploadProgressTotalBytes;
 	int uploadProgressTotalBytes;
 
 
+	// Download progress indicator, probably an NSProgressIndicator or UIProgressView
 	id downloadProgressDelegate;
 	id downloadProgressDelegate;
+	
+	// Total amount downloaded so far for all requests in this queue
 	int downloadProgressBytes;
 	int downloadProgressBytes;
-	int downloadProgressTotalBytes;
 	
 	
-	SEL requestDidFinishSelector;
-	SEL requestDidFailSelector;
-	SEL queueDidFinishSelector;
+	// Total amount to be downloaded for all requests in this queue - requests add to this figure as they receive Content-Length headers
+	int downloadProgressTotalBytes;
 	
 	
+	// When YES, the queue will cancel all requests when a request fails. Default is YES
 	BOOL shouldCancelAllRequestsOnFailure;
 	BOOL shouldCancelAllRequestsOnFailure;
 	
 	
 	int requestsCount;
 	int requestsCount;
 	int requestsCompleteCount;
 	int requestsCompleteCount;
 }
 }
 
 
-//
 
 
 // Called at the start of a request to add on the size of this upload to the total
 // Called at the start of a request to add on the size of this upload to the total
 - (void)incrementUploadSizeBy:(int)bytes;
 - (void)incrementUploadSizeBy:(int)bytes;

@@ -48,6 +48,8 @@
 - (void)setUploadProgressDelegate:(id)newDelegate
 - (void)setUploadProgressDelegate:(id)newDelegate
 {
 {
 	uploadProgressDelegate = newDelegate;
 	uploadProgressDelegate = newDelegate;
+	
+	// If the uploadProgressDelegate is an NSProgressIndicator, we set it's MaxValue to 1.0 so we can treat it similarly to UIProgressViews
 	SEL selector = @selector(setMaxValue:);
 	SEL selector = @selector(setMaxValue:);
 	if ([uploadProgressDelegate respondsToSelector:selector]) {
 	if ([uploadProgressDelegate respondsToSelector:selector]) {
 		double max = 1.0;
 		double max = 1.0;
@@ -64,6 +66,8 @@
 - (void)setDownloadProgressDelegate:(id)newDelegate
 - (void)setDownloadProgressDelegate:(id)newDelegate
 {
 {
 	downloadProgressDelegate = newDelegate;
 	downloadProgressDelegate = newDelegate;
+	
+	// If the downloadProgressDelegate is an NSProgressIndicator, we set it's MaxValue to 1.0 so we can treat it similarly to UIProgressViews
 	SEL selector = @selector(setMaxValue:);
 	SEL selector = @selector(setMaxValue:);
 	if ([downloadProgressDelegate respondsToSelector:selector]) {
 	if ([downloadProgressDelegate respondsToSelector:selector]) {
 		double max = 1.0;
 		double max = 1.0;
@@ -75,7 +79,7 @@
 	}	
 	}	
 }
 }
 
 
-//Only add ASIHTTPRequests to this queue
+// Only add ASIHTTPRequests to this queue!!
 - (void)addOperation:(NSOperation *)operation
 - (void)addOperation:(NSOperation *)operation
 {
 {
 	if ([operation isKindOfClass:[ASIHTTPRequest class]]) {
 	if ([operation isKindOfClass:[ASIHTTPRequest class]]) {
@@ -160,6 +164,7 @@
 	[ASIHTTPRequest setProgress:progress forProgressIndicator:downloadProgressDelegate];
 	[ASIHTTPRequest setProgress:progress forProgressIndicator:downloadProgressDelegate];
 }
 }
 
 
+// Since this queue takes over as the delegate for all requests it contains, it should forward authorisation requests to its own delegate
 - (void)authorizationNeededForRequest:(ASIHTTPRequest *)request
 - (void)authorizationNeededForRequest:(ASIHTTPRequest *)request
 {
 {
 	if ([delegate respondsToSelector:@selector(authorizationNeededForRequest:)]) {
 	if ([delegate respondsToSelector:@selector(authorizationNeededForRequest:)]) {

@@ -83,11 +83,47 @@
 	requestThatShouldFail = [[ASIHTTPRequest alloc] initWithURL:url];
 	requestThatShouldFail = [[ASIHTTPRequest alloc] initWithURL:url];
 	[networkQueue addOperation:requestThatShouldFail];
 	[networkQueue addOperation:requestThatShouldFail];
 
 
+	url = [[[NSURL alloc] initWithString:@"http://allseeing-i.com/asi-http-request/tests/broken"] autorelease];
+	ASIHTTPRequest *request5 = [[[ASIHTTPRequest alloc] initWithURL:url] autorelease];
+	[networkQueue addOperation:request5];
+	
+	
 	NSDate* endDate = [NSDate distantFuture];
 	NSDate* endDate = [NSDate distantFuture];
 	while (!complete) {
 	while (!complete) {
 		[[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode beforeDate:endDate];
 		[[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode beforeDate:endDate];
 	}
 	}
 	
 	
+	
+	BOOL success;
+	success = ([request1 error] == nil);
+	STAssertTrue(success,@"Request 1 failed");
+	
+	success = [[request1 dataString] isEqualToString:@"This is the expected content for the first string"];
+	STAssertTrue(success,@"Failed to download the correct data for request 1");
+	
+	success = ([request2 error] == nil);
+	STAssertTrue(success,@"Request 2 failed");
+	
+	success = [[request2 dataString] isEqualToString:@"This is the expected content for the second string"];
+	STAssertTrue(success,@"Failed to download the correct data for request 2");
+	
+	success = ([request3 error] == nil);
+	STAssertTrue(success,@"Request 3 failed");
+	
+	success = [[request3 dataString] isEqualToString:@"This is the expected content for the third string"];
+	STAssertTrue(success,@"Failed to download the correct data for request 3");
+	
+	success = ([requestThatShouldFail error] != nil);
+	STAssertTrue(success,@"Request 4 succeed when it should have failed");
+	
+	success = ([request5 error] == nil);
+	STAssertTrue(success,@"Request 5 failed");
+	
+	success = ([request5 responseStatusCode] == 404);
+	STAssertTrue(success,@"Failed to obtain the correct status code for request 5");
+
+
+	
 	[requestThatShouldFail release];
 	[requestThatShouldFail release];
 	
 	
 }
 }
@@ -124,8 +160,8 @@
 		[[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode beforeDate:endDate];
 		[[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode beforeDate:endDate];
 	}
 	}
 	
 	
-	[requestThatShouldFail release];
 	
 	
+	[requestThatShouldFail release];	
 }
 }
 
 
 - (void)requestFailedCancellingOthers:(ASIHTTPRequest *)request
 - (void)requestFailedCancellingOthers:(ASIHTTPRequest *)request
@@ -144,7 +180,6 @@
 - (void)queueFinished:(ASINetworkQueue *)queue
 - (void)queueFinished:(ASINetworkQueue *)queue
 {
 {
 	complete = YES;
 	complete = YES;
-
 }
 }