Improved documentation

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@22088 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,8 @@
+2005-11-24  fabien  <fabien@sonappart.net>
+
+	* Source/NSMatrix.m: Improved documentation, various cleanups
+	* Source/NSOpenPanel.m: Improved documentation
+
 2005-11-22  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Headers/Additions/GNUstepGUI/GSDrawFunctions.h:

Source/NSMatrix.m

@@ -1590,22 +1590,25 @@ static SEL getSel;
   return [self previousKeyView];
 }
 
+/**
+ */
 - (void) textDidBeginEditing: (NSNotification *)aNotification
 {
-  NSMutableDictionary *d;
+  NSMutableDictionary *dict;
+
+  dict = [[NSMutableDictionary alloc] initWithDictionary: 
+					[aNotification userInfo]];
+  AUTORELEASE (dict);
+  [dict setObject: [aNotification object] forKey: @"NSFieldEditor"];
 
-  d = [[NSMutableDictionary alloc] initWithDictionary: 
-				     [aNotification userInfo]];
-  AUTORELEASE (d);
-  [d setObject: [aNotification object] forKey: @"NSFieldEditor"];
   [nc postNotificationName: NSControlTextDidBeginEditingNotification
       object: self
-      userInfo: d];
+      userInfo: dict];
 }
 
 - (void) textDidChange: (NSNotification *)aNotification
 {
-  NSMutableDictionary *d;
+  NSMutableDictionary *dict;
   NSFormatter *formatter;
 
   // MacOS-X asks us to inform the cell if possible.
@@ -1613,14 +1616,14 @@ static SEL getSel;
 						 @selector(textDidChange:)])
     [_selectedCell textDidChange: aNotification];
 
-  d = [[NSMutableDictionary alloc] initWithDictionary: 
+  dict = [[NSMutableDictionary alloc] initWithDictionary: 
 				     [aNotification userInfo]];
-  AUTORELEASE (d);
+  AUTORELEASE (dict);
-  [d setObject: [aNotification object] forKey: @"NSFieldEditor"];
+  [dict setObject: [aNotification object] forKey: @"NSFieldEditor"];
 
   [nc postNotificationName: NSControlTextDidChangeNotification
       object: self
-      userInfo: d];
+      userInfo: dict];
 
   formatter = [_cell formatter];
   if (formatter != nil)
@@ -1979,6 +1982,10 @@ static SEL getSel;
     }
 }
 
+/**<p>Draws the cell at row <var>row</var> and column <var>column</var></p>
+   <p>See Also: [NSCell-drawWithFrame:inView:] -setDrawsCellBackground:
+   -drawsCellBackground</p>
+ */
 - (void) drawCellAtRow: (int)row column: (int)column
 {
   NSCell *aCell = [self cellAtRow: row column: column];
@@ -2024,6 +2031,10 @@ static SEL getSel;
     }
 }
 
+/** <p>(Un)Highlights the cell (if exists ) at row at row <var>row</var> 
+    and column <var>column</var>. and maks the cell rect for display.</p>
+    <p>See Also: -setNeedsDisplayInRect: [NSCell-setHighlighted:]</p>
+ */
 - (void) highlightCell: (BOOL)flag atRow: (int)row column: (int)column
 {
   NSCell	*aCell = [self cellAtRow: row column: column];
@@ -2035,6 +2046,12 @@ static SEL getSel;
     }
 }
 
+/**<p>Sends the cell action, if a NSMatrix's cell is selected 
+   and enabled, sends the NSMatrix action otherwise. Returns YES if
+   the action is succesfully sent. NO if a cell is selected but not enabled
+   or if an action can not be sent.</p>
+   <p>See Also: -sendAction:to: -selectedCell</p>   
+ */
 - (BOOL) sendAction
 {
   if (_selectedCell)
@@ -2113,6 +2130,8 @@ static SEL getSel;
     }
 }
 
+/** 
+ */
 - (void) sendDoubleAction
 {
   if ([_selectedCell isEnabled] == NO)
@@ -2922,17 +2941,20 @@ static SEL getSel;
   return _action;
 }
 
-/**
+/** <p>Sets the message to send when a double click occurs.
- * Sets the message to send when a double click occurs.<br />
+    NB: In GNUstep the following method does *not* set 
- * NB: In GNUstep the following method does *not* set 
+    ignoresMultiClick to NO as in the MacOS-X spec.
- * ignoresMultiClick to NO as in the MacOS-X spec.<br />
+    It simply sets the doubleAction, as in OpenStep spec.</p>
- * It simply sets the doubleAction, as in OpenStep spec.
+    <p>-doubleAction</p> 
  */
 - (void) setDoubleAction: (SEL)aSelector
 {
   _doubleAction = aSelector;
 }
 
+/** <p>Returns the action method, used when the user double clicks</p>
+    <p>See Also: -setDoubleAction:</p>
+ */
 - (SEL) doubleAction
 {
   return _doubleAction;
@@ -3013,11 +3035,17 @@ static SEL getSel;
   return _drawsCellBackground;
 }
 
+/** <p>Sets whether the NSMatrix resizes its cells automatically</p>
+    <p>See Also: -autosizesCells</p>
+ */
 - (void) setAutosizesCells: (BOOL)flag
 {
   _autosizesCells = flag;
 }
 
+/** <p>Returns whether the NSMatrix resizes its cells automatically</p>
+    <p>See Also: -autosizesCells</p>
+ */
 - (BOOL) autosizesCells
 {
   return _autosizesCells;

Source/NSOpenPanel.m

@@ -255,7 +255,8 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
   }
 }
 
-/**<p> Creates ( if needed ) and returns the shared NSOpenPanel instance</p> */
+/**<p>Creates ( if needed ) and returns the shared NSOpenPanel instance.</p> 
+*/
 + (NSOpenPanel *) openPanel
 {
   if (!_gs_gui_open_panel)
@@ -288,8 +289,8 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
  * Filtering Files
  */
 /**<p> Allows the user to select multiple files if flag is YES.
-   The default behavior is not to allow multiple selections</p>
+   The default behavior is not to allow multiple selections</p><p>See Also:
- <p>See Also: -allowsMultipleSelection</p>
+   -allowsMultipleSelection [NSBrowser-setAllowsMultipleSelection:]</p>
 */
 - (void) setAllowsMultipleSelection: (BOOL)flag
 {
@@ -297,17 +298,17 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
 }
 
 /**<p>Returns YES if the user is allowed to select multiple files. The
-    default behavior is not to allow mutiple selections.</p>
+   default behavior is not to allow mutiple selections.</p><p>See Also:
-    <p>See Also: -setAllowsMultipleSelection:</p>
+   -setAllowsMultipleSelection: [NSBrowser-allowsMultipleSelection]</p>
 */
 - (BOOL) allowsMultipleSelection
 {
   return [_browser allowsMultipleSelection];
 }
 
-/** <p>Allows the user to choose directories if flag is YES. The default 
+/**<p>Allows the user to choose directories if flag is YES. The default 
-    behavior is to allow choosing directories.</p>
+   behavior is to allow choosing directories.</p>
-    <p>See Also: -canChooseDirectories</p>
+   <p>See Also: -canChooseDirectories [NSBrowser-setAllowsBranchSelection:]</p>
 */
 - (void) setCanChooseDirectories: (BOOL)flag
 {
@@ -355,9 +356,9 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
     return nil;
 }
 
-/** <p>Returns an array containing the absolute paths (as NSString
+/**<p>Returns an array containing the absolute paths (as NSString
-    objects) of the selected files and directories.  If multiple
+   objects) of the selected files and directories.  If multiple
-    selections aren't allowed, the array contains a single name.</p>
+   selections aren't allowed, the array contains a single name.</p>
 */
 - (NSArray *) filenames
 {
@@ -420,9 +421,9 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
 /*
  * Running the NSOpenPanel
  */
-/** <p>Displays the open panel in a modal session, filtering for
+/**<p>Displays the open panel in a modal session, filtering for
-    files that have the specified types </p>
+   files that have the specified types </p>
-    <p>See Also: -runModalForDirectory:file:types:</p>
+   <p>See Also: -runModalForDirectory:file:types:</p>
 */
 - (int) runModalForTypes: (NSArray *)fileTypes
 {