Added comments and cleaned up code in the sections I added/modified

git-svn-id: https://svn.macports.org/repository/macports/branches/gsoc10-gui@70525 d073be05-634f-4543-b044-5fe20cf6d1d6

MacPorts_Framework/MPPort.m

@@ -388,6 +388,8 @@
 - (void)upgradeWithError:(NSError **)mError {
 	[self execPortProc:@"mportupgrade" withOptions:nil version:@"" error:mError];
 }
+
+//This function is called to initialize the array for the'default_variants' key for a port, which we can't do for all ports when loading
 - (void)checkDefaults
 {
 	//Check for default variants only if this is the first time we are checking
@@ -429,6 +431,8 @@
 
 }
 
+//This function is called to initiate the conflicts for a specific port, which we can't do for all ports when loading, much like
+//the default_variants
 - (void)checkConflicts;
 {
 	//Check for only if this is the first time we are checking

Pallet/MPActionLauncher.m

@@ -54,6 +54,8 @@ static MPActionLauncher *sharedActionLauncher = nil;
     NSError * error;
     NSArray *empty = [NSArray arrayWithObject: @""];
     [port installWithOptions:empty variants:empty error:&error];
+	//Check if we have received an error, send the apropriate notification, and if everything is fine
+	//send a notification to the main thread that we have completed our operation, and to advance the queue
 	if(errorReceived)
 		[self sendGrowlNotification: GROWL_INSTALLFAILED];
 	else
@@ -68,10 +70,13 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	errorReceived=NO;
     NSError * error;
     NSArray *empty = [NSArray arrayWithObject: @""];
-	
+	//Because we get the port and the variants mixed in an array, we copy the port to a local variable,
+	//and the variants array to a local array
 	MPPort* port = [portAndVariants objectAtIndex:0];
 	NSArray *variants = [portAndVariants objectAtIndex:1];
     [port installWithOptions:empty variants:variants error:&error];
+	//Check if we have received an error, send the apropriate notification, and if everything is fine
+	//send a notification to the main thread that we have completed our operation, and to advance the queue
 	if(errorReceived)
 		[self sendGrowlNotification: GROWL_INSTALLFAILED];
 	else
@@ -86,6 +91,8 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	errorReceived=NO;
     NSError * error;
     [port uninstallWithVersion:@"" error:&error];
+	//Check if we have received an error, send the apropriate notification, and if everything is fine
+	//send a notification to the main thread that we have completed our operation, and to advance the queue
 	if(errorReceived)
 		[self sendGrowlNotification: GROWL_UNINSTALLFAILED];
 	else
@@ -99,6 +106,8 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	errorReceived=NO;
     NSError * error;
     [port upgradeWithError:&error];
+	//Check if we have received an error, send the apropriate notification, and if everything is fine
+	//send a notification to the main thread that we have completed our operation, and to advance the queue
 	if(errorReceived)
 		[self sendGrowlNotification: GROWL_UPGRADEFAILED];
 	else
@@ -112,6 +121,8 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	errorReceived=NO;
     NSError * error;
     [[MPMacPorts sharedInstance] sync:&error];
+	//Check if we have received an error, send the apropriate notification, and if everything is fine
+	//send a notification to the main thread that we have completed our operation, and to advance the queue
 	if(errorReceived)
 		[self sendGrowlNotification: GROWL_SYNCFAILED];
 	else
@@ -125,9 +136,8 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	errorReceived=NO;
     NSError * error;
     [[MPMacPorts sharedInstance] selfUpdate:&error];
-	//NSLog(@"yay");
-	//NSInteger code = [error code];
-	//NSLog(@"Selfupdate Error Code %i", code);
+	//Check if we have received an error, send the apropriate notification, and if everything is fine
+	//send a notification to the main thread that we have completed our operation, and to advance the queue
 	if(errorReceived)
 		[self sendGrowlNotification: GROWL_SELFUPDATEFAILED];
 	else
@@ -142,8 +152,12 @@ static MPActionLauncher *sharedActionLauncher = nil;
     [[MPMacPorts sharedInstance] cancelCurrentCommand];
 }
 
+//sendGrowlNotification is the method used to send our Growl notifications, via the Growl framework. It takes one argument, which is the
+//type of notification we are sending, as defined in GrowlNotifications.h It initializes the strings we will be sending to the
+//Growl Framework that comprise our notification, and finaly sends the notification
 -(void) sendGrowlNotification:(int)type
 {
+	//The notification needs a title. We initialize an array containing the titles for each type of notification
 	NSString *growlTitles[GROWL_TYPES];
 	growlTitles[GROWL_INSTALL] = [NSString stringWithString: @"Installation Completed"];
 	growlTitles[GROWL_UNINSTALL] = [NSString stringWithString: @"Uninstall Completed"];
@@ -159,8 +173,8 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	growlTitles[GROWL_ALLOPS] = [NSString stringWithString: @"Operations Completed"];
 	growlTitles[GROWL_ALLOPSFAILED] = [NSString stringWithString: @"Operations Failed"];
 
-	NSString *growlDescriptions[GROWL_TYPES];
-	
+	//The notification also needs a description. We initialize an array containing the descriptions for each type of notification
+	NSString *growlDescriptions[GROWL_TYPES];	
 	growlDescriptions[GROWL_INSTALL] = [NSString stringWithString: @"Operation completed successfully"];
 	growlDescriptions[GROWL_UNINSTALL] = [NSString stringWithString: @"Operation completed successfully"];
 	growlDescriptions[GROWL_UPGRADE] = [NSString stringWithString: @"Operation completed successfully"];
@@ -175,8 +189,9 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	growlDescriptions[GROWL_ALLOPS] = [NSString stringWithString: @"All Operations Completed Succesfully"];
 	growlDescriptions[GROWL_ALLOPSFAILED] = [NSString stringWithString: @"Operations Failed"];
 
+	//And the notification also needs a name, which Growl uses to identify it. We initialize an array containing
+	//these names here
 	NSString *growlNotificationNames[GROWL_TYPES];
-	
 	growlNotificationNames[GROWL_INSTALL] = [NSString stringWithString: @"InstallCompleted"];
 	growlNotificationNames[GROWL_UNINSTALL] = [NSString stringWithString: @"UninstallCompleted"];
 	growlNotificationNames[GROWL_UPGRADE] = [NSString stringWithString: @"UpgradeCompleted"];
@@ -190,8 +205,13 @@ static MPActionLauncher *sharedActionLauncher = nil;
 	
 	growlNotificationNames[GROWL_ALLOPS] = [NSString stringWithString: @"OperationsCompleted"];
 	growlNotificationNames[GROWL_ALLOPSFAILED] = [NSString stringWithString: @"OperationsFailed"];
-
+	
+	
+	/*#################	These initializations should be moved to [init], and only call the following functions 	#################*/
+	
+	//Before we can send our messages, we need to call setGrowlDelegate once, due to a bug with the Growl Framework
 	[GrowlApplicationBridge setGrowlDelegate:(id) @""];
+	//And finaly, we send our notification, by calling notifyWithTitle with the appropriate title/description/name 
 	[GrowlApplicationBridge notifyWithTitle: growlTitles[type] description: growlDescriptions[type]\
 						   notificationName:growlNotificationNames[type] iconData:nil priority: 0\
 								   isSticky: NO clickContext:nil];

Pallet/MPActionsController.h

@@ -34,8 +34,10 @@ extern BOOL altWasPressed;
 	//Info Panel
 	IBOutlet NSPanel *infoPanel;
 	
+	//To make our checkbox management easier, we hold our checkboxes in array 
 	MPCheckbox* checkboxes[10];
 	
+	//We set 10 checkboxes, that will hold our port variants
 	IBOutlet MPCheckbox *chckbx0;
 	IBOutlet MPCheckbox *chckbx1;
 	IBOutlet MPCheckbox *chckbx2;

Pallet/MPActionsController.m

@@ -15,6 +15,7 @@
     [NSBundle loadNibNamed:@"Preferences" owner:self];
 }
 
+//After choosing the variants, this method is called when the user clicks on the Go button
 - (IBAction)installWithVariantsPerform:(id)sender {
 	if (altWasPressed)
 	{
@@ -34,6 +35,9 @@
 	for(UInt i=0; i<[[port valueForKey:@"variants"] count];i++)
 	{
 		//NSLog(@"%@",[[port valueForKey:@"variants"] objectAtIndex:i]);
+		
+		//If the checkbox is checked, the variant is added on the list. If it is a default_variant, a '+' is added in the name,
+		//to comply with the mportopen arguments
 		if ([checkboxes[i] state] == NSOnState)
 		{
 			if (![checkboxes[i] isDefault])
@@ -47,6 +51,8 @@
 		}
 		else if([checkboxes[i] isDefault])
 		{
+			//If the checkbox is unchecked, we need to check if it is a default_variant, and if so, add it in the list with '-'
+			//in the name, to let macports know that we wish to not use it
 			[variants addObject: [[port valueForKey:@"variants"] objectAtIndex:i]];
 			[variants addObject: [NSString stringWithString:@"-"]];
 			[variantsString appendString:@"-"];
@@ -55,13 +61,6 @@
 
 	}
 	//NSLog(@"End of Variants");
-		
-	/*
-	for(UInt i=0; i<[variants count]; i++)
-	{
-		NSLog(@"variants array at #%i: %@", i, [variants objectAtIndex:i]);
-	}
-	 */
 	
 	[self queueOperation:@"install+" portName:variantsString portObject:port variants: variants];
 	NSLog(@"%@",[port name]);
@@ -70,11 +69,13 @@
 		[self startQueue:nil];
 }
 
+//This method is called when the user clicks install with variants
 - (IBAction)installWithVariantsChoose:(id)sender 
 {
 	NSArray *selectedPorts = [ports selectedObjects];
 	id port = [selectedPorts objectAtIndex:0];
 	
+	//Only go through the fuss if there are variants, otherwise, perform a normal install
 	if([[port valueForKey:@"variants"] count] > 0)
 	{
 		checkboxes[0]=chckbx0;
@@ -88,10 +89,7 @@
 		checkboxes[8]=chckbx8;
 		checkboxes[9]=chckbx9;
 		
-		//Testing code
-		//checkboxes[0].conflictsWith = @"universal";
-		
-		
+		//Hide all checkboxes first
 		for(UInt i=0; i< 10;i++)
 		{
 			[checkboxes[i] setAlphaValue:0];
@@ -104,8 +102,7 @@
 		NSLog(@"Default variants count: %i", [defaultVariants count]);
 		for(UInt i=0; i<[[port valueForKey:@"variants"] count];i++)
 		{
-			//[checkboxes[1] setEnabled:NO];
-
+			//If the variant is included in the default_variants, then check it. Otherwise leave it unchecked
 			//NSLog(@"%@",[[port valueForKey:@"variants"] objectAtIndex:i]);
 			if(defaultVariants != nil && [defaultVariants indexOfObject:[[port valueForKey:@"variants"] objectAtIndex:i]] != NSNotFound)
 			{
@@ -118,8 +115,7 @@
 				[checkboxes[i] setState:NSOffState];
 				[checkboxes[i] setIsDefault:NO];\
 			}
-
-
+			//Show all existing variants, and set their titles
 			[checkboxes[i] setAlphaValue:1];
 			NSAttributedString *tempString = [[NSAttributedString alloc]\
 											  initWithString:[[port valueForKey:@"variants"] objectAtIndex:i]\
@@ -128,11 +124,10 @@
 			 
 		}
 		//NSLog(@"End of Variants");
+		//Call setConflicts to initialize conflicting variants in the GUI
 		[self setConflicts:port];
 
-		
 		[variantsPanel makeKeyAndOrderFront:self];
-		//[chckbx2 setTitle:@"hehe"];
 		//[variantsPanel makeFirstResponder:[tableController mainWindow]];
 	}
 	else
@@ -262,7 +257,8 @@
 	
 	for(UInt j=0;j<[[sender conflictsWith] count]; j++)
 	{
-		//Enable/disable our conflicts depending on what we are doing
+		//If we are checking the checkbox, then disable and uncheck the conflicting ones
+		//If we are unchecking the checkbox, enable the conflicting ones
 		for(UInt i=0; i<10; i++)
 		{
 			if ([[checkboxes[i] title] isEqualToString:[[sender conflictsWith] objectAtIndex:j]])
@@ -284,7 +280,8 @@
 	[port checkConflicts];
 
 	NSArray *conflicts = [port objectForKey:@"conflicts"];
-	
+	//For each conflict in the array, check which checkbox/variant has the same name as the conflict, and
+	//call the setConflictsWith method to add the conflicting checkbox to the conflictsWith array
 	for(UInt j=0; j< [conflicts count];j++)
 	{
 		UInt i;
@@ -295,7 +292,6 @@
 				break;
 			}
 		 }
-		//NSLog(@"checkbox that conflicts: %@", [checkboxes[i] title]);
 		[checkboxes[i] setConflictsWith:[[conflicts objectAtIndex:j] objectForKey:[checkboxes[i] title]]];
 	}
 }
@@ -336,9 +332,9 @@
     }
 }
 
+//This is called when clicking on the 'start queue' button, or clicking on an operation while holding the alt key
 -(void) startQueue:(id) sender
 {
-	//[queue selectNext:nil];
 	NSLog(@"Starting Queue");
 	NSUInteger index;
 	index = [queueArray count]-1;
@@ -347,31 +343,17 @@
 	[queue setSelectionIndex: 0];
 	queueCounter=0;
 	
+	//We add ourselves as an observer in the Notification Center, and call advanceQueue whenever we receive an 'advanceQ' notification
 	[[NSNotificationCenter defaultCenter] addObserver:self
 											 selector:@selector(advanceQueue)
 												 name:@"advanceQ" object:nil];
+	//We start the operations by advancing in the queue once. When that operation is completed, it will
+	//automatically advance to the next queue by sending an advanceQ notification.
 	[self advanceQueue];
-	
-	for(i=0; i<=index+10; i++)
-	{
-		/*
-		//We select each object from the array
-		[queue setSelectionIndex:i];
-		//We sleep the process for debugging puproses
-		sleep(3);
-		//We take the array of selected objects
-		NSArray *wtf = [queue selectedObjects];
-		//We then take the dictionary
-		NSMutableDictionary *dict = [NSMutableDictionary dictionaryWithDictionary:[wtf objectAtIndex:0]];
-		//And we print the operations
-		NSLog(@"Port %@ Operation %@",[dict objectForKey:@"port"], [dict objectForKey:@"operation"]);
-		 */
-		
-	}
-	//[queue setSelectionIndex:index];
-	//[queue selectNext:nil];
 }
 
+//This method is called to move through the queue and perform all the operations one by one. Each time this method is called,
+//we advance one spot in the queue
 -(void) advanceQueue
 {
 	NSUInteger index=queueCounter;
@@ -432,6 +414,7 @@
 	}
 	else
 	{
+		//If we are done, we remove ourselves as an observer from the Notification Center, and we notify the user
 		[[NSNotificationCenter defaultCenter] removeObserver:self name:@"advanceQ" object:nil];
 		
 		int allops=GROWL_ALLOPS;
@@ -444,8 +427,11 @@
 	
 }
 
+//This method is called when adding a new operation on the queue. Its inputs are the operation to be performed, the port name, the 
+//equivalent port object, and the variants
 -(void) queueOperation:(NSString*)operation portName:(NSString*)name portObject: (id) port variants: (NSMutableArray*) variants
 {
+	//We set the operation's icon
 	NSImage *image;
 	if ([operation isEqualToString:@"install"])
 	{
@@ -472,10 +458,9 @@
 		image = [NSImage imageNamed:@"TB_Selfupdate.icns"];
 	}
 	
-	
+	//If we have variants, print them out for debugging purposes
 	if(variants!=nil)
 	{
-		NSLog(@"yay");
 		for(UInt i=0; i<[variants count]; i++)
 		{
 			NSLog(@"variants array at #%i: %@", i, [variants objectAtIndex:i]);
@@ -483,9 +468,8 @@
 	}
 	
 	NSLog(@"Queueing our Operation");
+	//Add the operation to the queue
 	[queue addObject:[NSMutableDictionary dictionaryWithObjectsAndKeys:operation, @"operation", name, @"port", port, @"object", image, @"image", variants, @"variants", nil]];
-	//[queue addObject: tempDict];
-	//[queue retain];
 }
 
 /*
@@ -497,9 +481,9 @@
 }
 */
 
+//This is called when we have the alt key pressed, so that we clear the queue before adding and performing our new operation
 -(void) clearQueue
 {
-	//NSLog(@"We have the alt key pressed");
 	NSIndexSet *tempIndex = [NSIndexSet indexSetWithIndexesInRange:NSMakeRange(0, [queueArray count])];
 	[queue removeObjectsAtArrangedObjectIndexes:tempIndex];
 	

Pallet/MPCheckbox.h

@@ -8,7 +8,8 @@
 
 #import <Cocoa/Cocoa.h>
 
-
+//MPCheckbox is a custom NSButton class, that we use for our variants checkboxes.
+//Each variant is represented by a checkbox. This checkbox also stores wether it is a default variant, and a list of conflicting variants
 @interface MPCheckbox : NSButton {
 
 	

Pallet/MPPortTableView.h

@@ -8,6 +8,7 @@
 
 #import <Cocoa/Cocoa.h>
 
+//A variable that holds the last status of the ALT key, to use it when clicking on a button
 BOOL altWasPressed;
 
 @interface MPPortTableView : NSTableView {

Pallet/MPPortTableView.m

@@ -23,7 +23,6 @@
         ([[theEvent characters] characterAtIndex:0] == 27 && [quickLookPanel isVisible])) {
         if ([quickLookPanel isVisible]) {
             [quickLookPanel close];
-			//[variantsPanel close];
         } else {
             [quickLookPanel makeKeyAndOrderFront:self];
             [quickLookPanel makeFirstResponder:self];
@@ -33,9 +32,10 @@
     }
 }
 
-
+//flagsChanged is called every time a flag-changing key is pressed, like alt-ctrl-cmd etc
 -(void)flagsChanged:(NSEvent *)theEvent
 {
+	//We check if Alt is pressed
 	if([theEvent modifierFlags]&NSAlternateKeyMask)
 	{
 		NSLog(@"Alt is pressed");
@@ -43,6 +43,8 @@
 	}
 	else
 	{
+		//If not, then if it's no longer pressed, we update our value. Otherwise, it means that
+		//this has nothing to do with us, so we let the system handle the flag change
 		if(altWasPressed)
 		{
 			NSLog(@"Alt is released");

Pallet/MPQueueTableView.m

@@ -13,20 +13,6 @@
 
 
 -(void)keyDown:(NSEvent *)theEvent {
-	/*
-    if ([[theEvent characters] characterAtIndex:0] == NSDeleteCharacter || [[theEvent characters] characterAtIndex:0] == NSBackspaceCharacter && [variantsPanel isVisible])) {
-		NSLog(@"wtf1");
-        if ([variantsPanel isVisible]) {
-            [variantsPanel close];
-			//[variantsPanel close];
-        } else {
-            [variantsPanel makeKeyAndOrderFront:self];
-        }
-    } else {
-		NSLog(@"wtf2");
-        [super keyDown:theEvent];
-    }
-	 */
 	if ([[theEvent characters] characterAtIndex:0] == NSDeleteCharacter || [[theEvent characters] characterAtIndex:0] == NSBackspaceCharacter)
 	{
 		NSLog(@"Deleting our shit");

Pallet/PortsTableController.m

@@ -107,20 +107,7 @@
 
 /****************** Drawer ******************/
 
-/* Our drawer is created programmatically rather than in IB, and has a 
- fixed size both vertically and horizontally.  The fixed vertical size is achieved
- by setting min and max content sizes equal to the content size.  The fixed horizontal
- size is achieved by setting leading and trailing offsets when the parent window resizes. */ 
-/*
-- (void)setupDrawer {
-    NSSize contentSize = NSMakeSize(150, 150);
-    drawer = [[NSDrawer alloc] initWithContentSize:contentSize preferredEdge:NSMinXEdge];
-    [drawer setParentWindow:mainWindow];
-    [drawer setMinContentSize:contentSize];
-    [drawer setMaxContentSize:contentSize];
-}
- */
-
+//These are the functions needed for our drawer. In addition to open/close, we implemented toggle as well
 - (IBAction)open:(id)sender {[drawer openOnEdge:NSMinXEdge];}
 
 - (IBAction)close:(id)sender {[drawer close];}
@@ -133,19 +120,5 @@
         [drawer openOnEdge:NSMinXEdge];
     }
 }
-/*
-- (void)setDrawerOffsets {
-    [drawer setLeadingOffset:30];
-    // we want a drawer width of approximately 220 unscaled.  Figure out an offset to accomplish that size.
-    //CGFloat drawerWidth = 220 * [mainWindow userSpaceScaleFactor];
-    [drawer setTrailingOffset: 30];
-}
-
-- (void)awakeFromNib {
-    [self setupDrawer];
-    [self setDrawerOffsets];
-	//[self openDrawer:(id) nil];
-}
-*/
 
 @end