Added documentation. Corrected a minor issue.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/apps/gorm/trunk@21547 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,11 @@
+2005-07-27 01:47 Gregory John Casamento <greg_casamento@yahoo.com>
+
+	* GormCore/GormDocument.h: Added documentation.
+	* GormCore/GormDocument.m: Removed commented code.  Corrected 
+	problem in [GormDocument instantiateClass:] when switching to
+	the objects view.
+	* GormCore/GormWindowEditor.h: Added documentation.
+
 2005-07-26 22:56 Gregory John Casamento <greg_casamento@yahoo.com>
 
 	* GormCore/GNUmakefile: Added new GormWindowEditor.h file.

GormCore/GormDocument.h

@@ -78,36 +78,154 @@
 }
 
 /* Archiving objects */
+
+/**
+ * Start the archiving process.
+ */
 - (void) beginArchiving;
+
+/**
+ * Stop the archiving process.
+ */
 - (void) endArchiving;
 
 /* Handle notifications */
+
+/**
+ * Handle all notifications.   Checks the value of [aNotification name]
+ * against the set of notifications this class responds to and takes
+ * appropriate action.
+ */
 - (void) handleNotification: (NSNotification*)aNotification;
 
 /* Document management */
+
+/**
+ * Returns YES, if document is active.
+ */
 - (BOOL) isActive;
+
+/**
+ * Return YES, if anObject is visible at launch time.
+ */
 - (BOOL) objectIsVisibleAtLaunch: (id)anObject;
+
+
+/**
+ * Return YES, if anObject is deferred.
+ */
 - (BOOL) objectIsDeferred: (id)anObject;
+
+/**
+ * This assumes we have an empty document to start with - the loaded
+ * document is merged in to it.
+ */
 - (id) loadDocument: (NSString*)path;
+
+/**
+ * This assumes we have an empty document to start with - the loaded
+ * document is merged in to it.
+ */
 - (id) openDocument: (id)sender;
+
+/**
+ * To revert to a saved version, we actually load a new document and
+ * close the original document, returning the id of the new document.
+ */
 - (id) revertDocument: (id)sender;
+
+/**
+ * Save the document.  If this is called when documentPath is nil, 
+ * then saveGormDocument: will call it to define the path.
+ */
 - (BOOL) saveAsDocument: (id)sender;
+
+/**
+ * Archives the .gorm file.  Creates the directory and all of the
+ * contents using the archiver and other class manager.
+ */
 - (BOOL) saveGormDocument: (id)sender;
+
+/**
+ * Creates a blank document depending on the value of type.
+ * If type is "Application", "Inspector" or "Palette" it creates 
+ * an appropriate blank document for the user to start with.
+ */
 - (void) setupDefaults: (NSString*)type;
+
+/**
+ * Marks this document as the currently active document.  The active document is
+ * the one being edited by the user.
+ */
 - (void) setDocumentActive: (BOOL)flag;
+
+/**
+ * Add object to the visible at launch list.
+ */
 - (void) setObject: (id)anObject isVisibleAtLaunch: (BOOL)flag;
+
+/**
+ * Add object to the defferred list.
+ */
 - (void) setObject: (id)anObject isDeferred: (BOOL)flag;
+
+/**
+ * The document window.
+ */
 - (NSWindow*) window;
+
+/**
+ * Determine if the document should be closed or not.
+ */
 - (BOOL) couldCloseDocument;
+
+/**
+ * Called when the document window close is selected.
+ */
 - (BOOL) windowShouldClose: (id)sender;
+
+/**
+ * Returns YES, if obj is a top level object.
+ */
 - (BOOL) isTopLevelObject: (id)obj;
+
+/**
+ * Forces the closing of all editors in the document.
+ */
 - (void) closeAllEditors;
+
+/**
+ * Create resource manager instances for all registered classes.
+ */
 - (void) createResourceManagers;
+
+/**
+ * The list of all resource managers.
+ */
 - (NSArray *) resourceManagers;
+
+/**
+ * Get the resource manager which handles the content on pboard.
+ */
 - (IBResourceManager *) resourceManagerForPasteboard: (NSPasteboard *)pboard;
+
+/**
+ * Switch to the top level editor responsible for a given type.  This allows the
+ * document in the view to switch to the view which is appropriate for the resource
+ * being dragged in.
+ */
 - (void) changeToTopLevelEditorAcceptingTypes: (NSArray *)types 
                                   andFileType: (NSString *)fileType;
+
+/**
+ * Switches to the view using the specified tag.  
+ * They are 0=objects, 1=images, 2=sounds, 3=classes, 4=file prefs.
+ */
 - (void) changeToViewWithTag: (int)tag;
+
+/**
+ * Returns all pasteboard types registered for with the IBResourceManager.
+ */
 - (NSArray *) allManagedPboardTypes;
 
 /* Language translation */
@@ -129,33 +247,94 @@
 - (void) removeAllInstancesOfClass: (NSString *)classNamed;
 
 /* Sound & Image support */
+
+/**
+ * Open a sound and load it into the document.
+ */
 - (id) openSound: (id)sender;
+
+/**
+ * Open an image and copy it into the document.
+ */
 - (id) openImage: (id)sender;
 
 /* Connections */
+
+/**
+ * Build our reverse mapping information and other initialisation
+ */
 - (void) rebuildObjToNameMapping;
+
+/**
+ * Removes all connections given action or outlet with the specified label 
+ * (paramter name) class name (parameter className). 
+ */
 - (BOOL) removeConnectionsWithLabel: (NSString *)name
                       forClassNamed: (NSString *)className
                            isAction: (BOOL)action;
+/**
+ * Remove all connections to any and all instances of className.
+ */
 - (BOOL) removeConnectionsForClassNamed: (NSString *)name;
+
+/**
+ * Rename connections connected to an instance of on class to another.
+ */
 - (BOOL) renameConnectionsForClassNamed: (NSString *)name 
                                  toName: (NSString *)newName;
 
 /* class loading */
+
+/**
+ * Load a class into the document.
+ */
 - (id) loadClass: (id)sender;
 
-/* services/windows menus... */
+/*** services/windows menus... ***/
+
+/**
+ * Set the services menu.
+ */
 - (void) setServicesMenu: (NSMenu *)menu;
+
+/**
+ * Returns the services menu for the document.
+ */
 - (NSMenu *) servicesMenu;
+
+/**
+ * Sets the windows menu.
+ */
 - (void) setWindowsMenu: (NSMenu *)menu;
+
+/**
+ * Returns the menu which will be the windows menu for the document.
+ */
 - (NSMenu *) windowsMenu;
 
-/* first responder/font manager */
+/*** first responder/font manager ***/
+
+/**
+ * Returns stand-in object for fontManager.
+ */
 - (id) fontManager;
+
+/**
+ * Returns stand-in object for firstResponder
+ */
 - (id) firstResponder;
 
 /* Layout */
+
+/**
+ * Arrages selected objects based on the either in front of or in
+ * back of the view stack.
+ */ 
 - (void) arrangeSelectedObjects: (id)sender;
+
+/**
+ * Aligns selected objects on a given axis.
+ */
 - (void) alignSelectedObjects: (id)sender;
 
 /* 
@@ -166,9 +345,25 @@
 @end
 
 @interface GormDocument (MenuValidation)
+
+/**
+ * Returns TRUE if the document is editing instance/objects.
+ */
 - (BOOL) isEditingObjects;
+
+/**
+ * Returns TRUE if the document is editing images.
+ */
 - (BOOL) isEditingImages;
+
+/**
+ * Returns TRUE if the document is editing sounds.
+ */
 - (BOOL) isEditingSounds;
+
+/**
+ * Returns TRUE if the document is editing classes.
+ */
 - (BOOL) isEditingClasses;
 @end
 

GormCore/GormDocument.m

@@ -330,19 +330,10 @@ static NSImage  *fileImage = nil;
 	  [soundsScrollView setDocumentView: soundsView];
 	  RELEASE(soundsView);
 
-	  // classes...
-	  // classesScrollView = [[NSScrollView alloc] initWithFrame: scrollRect];
-	  // [classesScrollView setHasVerticalScroller: YES];
-	  // [classesScrollView setHasHorizontalScroller: NO];
-	  // [classesScrollView setAutoresizingMask:
-	  //		       NSViewHeightSizable|NSViewWidthSizable];
-	  // [classesScrollView setBorderType: NSBezelBorder];
-	  
+	  /* classes view */
 	  mainRect.origin = NSMakePoint(0,0);
 	  classesView = [(GormClassEditor *)[GormClassEditor alloc] initWithDocument: self];
 	  [classesView setFrame: mainRect];
-	  // [classesScrollView setDocumentView: classesView];
-	  // RELEASE(classesView);	  
 	  
 	  /*
 	   * Set the objects view as the initial view the user's see on startup.
@@ -784,18 +775,21 @@ static NSImage  *fileImage = nil;
     case 0: // objects
       {
 	[selectionBox setContentView: scrollView];
+	[toolbar setSelectedItemIdentifier: @"ObjectsItem"];
 	[self setSelectionFromEditor: objectsView];
       }
       break;
     case 1: // images
       {
 	[selectionBox setContentView: imagesScrollView];
+	[toolbar setSelectedItemIdentifier: @"ImagesItem"];
 	[self setSelectionFromEditor: imagesView];
       }
       break;
     case 2: // sounds
       {
 	[selectionBox setContentView: soundsScrollView];
+	[toolbar setSelectedItemIdentifier: @"SoundsItem"];
 	[self setSelectionFromEditor: soundsView];
       }
       break;
@@ -811,11 +805,13 @@ static NSImage  *fileImage = nil;
 	    id obj = [selection objectAtIndex: 0];
 	    [classesView selectClassWithObject: obj];
 	  }
+	[toolbar setSelectedItemIdentifier: @"ClassesItem"];
 	[self setSelectionFromEditor: classesView];
       }
       break;
     case 4: // file prefs
       {
+	[toolbar setSelectedItemIdentifier: @"FileItem"];
 	[selectionBox setContentView: filePrefsView];
       }
       break;
@@ -829,25 +825,21 @@ static NSImage  *fileImage = nil;
   if([objectsView acceptsTypeFromArray: types] &&
      fileType == nil)
     {
-      [toolbar setSelectedItemIdentifier: @"ObjectsItem"];
       [self changeToViewWithTag: 0];
     }
   else if([imagesView acceptsTypeFromArray: types] &&
 	  [[imagesView fileTypes] containsObject: fileType])
     {
-      [toolbar setSelectedItemIdentifier: @"ImagesItem"];
       [self changeToViewWithTag: 1];
     }
   else if([soundsView acceptsTypeFromArray: types] &&
 	  [[soundsView fileTypes] containsObject: fileType])
     {
-      [toolbar setSelectedItemIdentifier: @"SoundsItem"];
       [self changeToViewWithTag: 2];
     }
   else if([classesView acceptsTypeFromArray: types] &&
 	  [[classesView fileTypes] containsObject: fileType])
     {
-      [toolbar setSelectedItemIdentifier: @"ClassesItem"];
       [self changeToViewWithTag: 3];
     }
 }
@@ -1695,7 +1687,7 @@ static NSImage  *fileImage = nil;
 
       // go to the class which was just loaded in the classes view...
       [classesView reloadData];
-      [selectionBox setContentView: classesView];
+      [self changeToViewWithTag: 3];
 
       if(newClass != nil)
 	{
@@ -1769,8 +1761,8 @@ static NSImage  *fileImage = nil;
 	  [classManager setCustomClass: object
 			forName: name];
 	}
-      
-      [selectionBox setContentView: scrollView];
+
+      [self changeToViewWithTag: 0];
       NSLog(@"Instantiate NSView subclass %@",object);	      
     }
   else
@@ -1779,9 +1771,8 @@ static NSImage  *fileImage = nil;
 				      frame: NSMakeRect(0,0,0,0)];
       
       [self setName: nil forObject: item];
-      [self attachObject: item toParent: nil];
-      
-      [selectionBox setContentView: scrollView];
+      [self attachObject: item toParent: nil];      
+      [self changeToViewWithTag: 0];
     }
   
   return self;
@@ -3813,7 +3804,7 @@ static NSImage  *fileImage = nil;
 }
 
 /**
- * Return font manager standin.
+ * Return font manager stand in.
  */
 - (id) fontManager
 {

GormCore/GormWindowEditor.h

@@ -96,12 +96,26 @@
  */
 - (unsigned int) draggingSourceOperationMaskForLocal: (BOOL)flag;
 
-
+/**
+ * Make current selection visible.
+ */
 - (void) makeSelectionVisible: (BOOL)flag;
 
 - (id<IBEditors>) openSubeditorForObject: (id)anObject;
+
+/**
+ * Order the edited window to the front.
+ */
 - (void) orderFront;
+
+/**
+ * Paste from pasteboard.
+ */
 - (void) pasteInSelection;
+
+/**
+ * Reset object, redisplays the window.
+ */
 - (void) resetObject: (id)anObject;
 @end