Improved documentation

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

ChangeLog

@@ -1,6 +1,10 @@
 2005-11-18  fabien  <fabien@sonappart.net>
 
 	* Source/NSSliderCell.m: Improved documentation
+	* Source/NSTextField.m: Improved documentation
+	* Source/NSTextFieldCell.m: Improved documentation
+	* Source/NSSavePanel.m: Improved documentation
+	* Source/NSOpenPanel.m: Improved documentation
 
 2005-11-17  fabien  <fabien@sonappart.net>
 

Source/NSOpenPanel.m

@@ -255,10 +255,7 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
   }
 }
 
-/*
+/**<p> Creates ( if needed ) and returns the shared NSOpenPanel instance</p> */
- * Accessing the NSOpenPanel shared instance
- */
-/** Returns the shared NSOpenPanel instance */
 + (NSOpenPanel *) openPanel
 {
   if (!_gs_gui_open_panel)
@@ -290,47 +287,62 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
 /*
  * Filtering Files
  */
-/** Allows the user to select multiple files if flag is YES. */
+/**<p> Allows the user to select multiple files if flag is YES.
+   The default behavior is not to allow multiple selections</p>
+ <p>See Also: -allowsMultipleSelection</p>
+*/
 - (void) setAllowsMultipleSelection: (BOOL)flag
 {
   [_browser setAllowsMultipleSelection: flag];
 }
 
-/** Returns YES if the user is allowed to select multiple files. The
+/**<p>Returns YES if the user is allowed to select multiple files. The
-    default behavior is not to allow mutiple selections. */
+    default behavior is not to allow mutiple selections.</p>
+    <p>See Also: -setAllowsMultipleSelection:</p>
+*/
 - (BOOL) allowsMultipleSelection
 {
   return [_browser allowsMultipleSelection];
 }
 
-/** Allows the user to choose directories if flag is YES. */
+/** <p>Allows the user to choose directories if flag is YES. The default 
+    behavior is to allow choosing directories.</p>
+    <p>See Also: -canChooseDirectories</p>
+*/
 - (void) setCanChooseDirectories: (BOOL)flag
 {
   _canChooseDirectories = flag;
   [_browser setAllowsBranchSelection: flag];
 }
 
-/** Returns YES if the user is allowed to choose directories  The
+/** <p>Returns YES if the user is allowed to choose directories  The
-    default behavior is to allow choosing directories. */
+    default behavior is to allow choosing directories.</p>
+    <p>See Also: -setCanChooseDirectories:</p>
+ */
 - (BOOL) canChooseDirectories
 {
   return _canChooseDirectories;
 }
 
-/** Allows the user to choose files if flag is YES */
+/** <p>Allows the user to choose files if flag is YES.The default behavior it
+    to allow choosing files. <p>See Also: -canChooseFiles</p>
+*/
 - (void) setCanChooseFiles: (BOOL)flag
 {
   _canChooseFiles = flag;
 }
 
-/** Returns YES if the user is allowed to choose files.  The
+/**<p>Returns YES if the user is allowed to choose files.  The
-    default behavior it to allow choosing files.  */
+    default behavior it to allow choosing files.</p>
+    <p>See Also: -setCanChooseFiles:</p>
+*/
 - (BOOL) canChooseFiles
 {
   return _canChooseFiles;
 }
 
-/** Returns the absolute path of the file selected by the user.  */
+/** <p>Returns the absolute path of the file selected by the user.</p>
+*/
 - (NSString*) filename
 {
   NSArray *ret;
@@ -343,9 +355,9 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
     return nil;
 }
 
-/** 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.
+    selections aren't allowed, the array contains a single name.</p>
 */
 - (NSArray *) filenames
 {
@@ -408,8 +420,9 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
 /*
  * Running the NSOpenPanel
  */
-/** 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 
+    files that have the specified types </p>
+    <p>See Also: -runModalForDirectory:file:types:</p>
 */
 - (int) runModalForTypes: (NSArray *)fileTypes
 {
@@ -418,10 +431,11 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
 			      types: fileTypes];
 }
 
-/** Displays the open panel in a modal session, with the directory
+/** <p>Displays the open panel in a modal session, with the directory
     path shown and file name (if any) selected. Files are filtered for the
     specified types. If the directory is nil, then the directory shown in 
-    the open panel is the last directory selected.
+    the open panel is the last directory selected.</p>
+    <p>See Also: -runModalForTypes:</p>
 */
 - (int) runModalForDirectory: (NSString *)path
 			file: (NSString *)name

Source/NSSavePanel.m

@@ -631,7 +631,8 @@ selectCellWithString: (NSString*)title
     }
 }
 
-/** Returns the shared NSSavePanel instance */
+/** <p>Creates ( if needed) and returns the shared NSSavePanel instance</p>
+ */
 + (NSSavePanel *) savePanel
 {
   if (_gs_gui_save_panel == nil)
@@ -681,13 +682,13 @@ selectCellWithString: (NSString*)title
   return self;
 }
 
-/** Sets an accessory view which is shown near the bottom of the
+/** <p>Sets an accessory view which is shown near the bottom of the
     panel. The panel is automatically expanded with enough room to
     show the extra view. You can use this extra view to customize
     various characteristics of the file selection mechanism. For instance
     you could add a popup button which allows the user to select the
     format that the file is saved in (e.g. rtf or txt). See
-    also -validateVisibleColumns .
+    also -validateVisibleColumns .</p><p>See Also: -accessoryView</p>
 */
 - (void) setAccessoryView: (NSView*)aView
 {
@@ -795,12 +796,11 @@ selectCellWithString: (NSString*)title
     }
 }
 
-/**
+/**<p>Sets the title of the NSSavePanel to title. By default, 
- * Sets the title of the NSSavePanel to title. By default, 
+  'Save' is the title string. If you adapt the NSSavePanel 
- * 'Save' is the title string. If you adapt the NSSavePanel 
+  for other uses, its title should reflect the user action 
- * for other uses, its title should reflect the user action 
+  that brings it to the screen.</p><p>See Also: -title</p>
- * that brings it to the screen.
+*/
- */
 - (void) setTitle: (NSString*)title
 {
   [_titleField setStringValue: title];
@@ -810,30 +810,35 @@ selectCellWithString: (NSString*)title
   [_titleField sizeToFit];
 }
 
-/** Returns the title of the save panel */
+/**<p>Returns the title of the save panel </p>
+ <p>See Also: -setTitle:</p>
+*/
 - (NSString*) title
 {
   return [_titleField stringValue];
 }
 
-/**
+/**<p> Returns the prompt of the Save panel field that holds 
- * Returns the prompt of the Save panel field that holds 
+  the current pathname or file name. By default this 
- * the current pathname or file name. By default this 
+  prompt is 'Name: '.</p><p>See Also: -prompt</p>
- * prompt is 'Name: '.
+*/
- */
 - (void) setPrompt: (NSString*)prompt
 {
   [[_form cellAtIndex: 0] setTitle: prompt];
   [_form setNeedsDisplay: YES];
 }
 
-/** Returns the prompt used in the current path field.  */
+/**<p>Returns the prompt used in the current path field.</p>
+ <p>See Also: -setPrompt:</p>
+*/
 - (NSString*) prompt
 {
   return [[_form cellAtIndex: 0] title];
 }
 
-/** Returns the accesory view (if any). */
+/** <p>Returns the accesory view (if any).</p>
+    <p>See Also: -setAccessoryView:</p> 
+*/
 - (NSView*) accessoryView
 {
   return _accessoryView;
@@ -862,9 +867,9 @@ selectCellWithString: (NSString*)title
 }
 
 
-/**
+/** <p>Sets the current path name in the Save panel's browser. 
- * Sets the current path name in the Save panel's browser. 
+    The path argument must be an absolute path name.</p>
- * The path argument must be an absolute path name.
+    <p>See Also: -directory</p>
  */
 - (void) setDirectory: (NSString*)path
 {
@@ -881,24 +886,22 @@ selectCellWithString: (NSString*)title
     }
 }
 
-/**
+/**<p> Specifies the type, a file name extension to be appended to 
- * Specifies the type, a file name extension to be appended to 
+   any selected files that don't already have that extension;
- * any selected files that don't already have that extension;
+   The argument type should not include the period that begins 
- * The argument type should not include the period that begins 
+   the extension.  Invoke this method each time the Save panel 
- * the extension.  Invoke this method each time the Save panel 
+   is used for another file type within the application.  If
- * is used for another file type within the application.  If
+   you do not invoke it, or set it to empty string or nil, no
- * you do not invoke it, or set it to empty string or nil, no
+   extension will be appended, indicated by an empty string
- * extension will be appended, indicated by an empty string
+   returned from -requiredFileType .</p><p>See Also: -requiredFileType</p>
- * returned from -requiredFileType .
  */
 - (void) setRequiredFileType: (NSString*)fileType
 {
   ASSIGN(_requiredFileType, fileType);
 }
 
-/**
+/**<p>Returns the required file type. The default, indicated by empty string,
- * Returns the required file type. The default, indicated by empty string,
+ * is no required file type.</p><p>See Also: -setRequiredFileType:</p>
- * is no required file type.
  */
 - (NSString*) requiredFileType
 {
@@ -933,27 +936,26 @@ selectCellWithString: (NSString*)title
   return _treatsFilePackagesAsDirectories;
 }
 
-/**
+/**<p> Sets the NSSavePanel's behavior for displaying file packages 
- * Sets the NSSavePanel's behavior for displaying file packages 
+   (for example, MyApp.app) to the user.  If flag is YES, the 
- * (for example, MyApp.app) to the user.  If flag is YES, the 
+   user is shown files and subdirectories within a file 
- * user is shown files and subdirectories within a file 
+   package.  If NO, the NSSavePanel shows each file package as 
- * package.  If NO, the NSSavePanel shows each file package as 
+   a file, thereby giving no indication that it is a directory.</p>
- * a file, thereby giving no indication that it is a directory.
+   <p>See Also: -treatsFilePackagesAsDirectories</p>
  */
 - (void) setTreatsFilePackagesAsDirectories: (BOOL)flag
 {
   _treatsFilePackagesAsDirectories = flag;
 }
 
-/**
+/**<p> Validates and possibly reloads the browser columns that are visible 
- * Validates and possibly reloads the browser columns that are visible 
  * in the Save panel by causing the delegate method 
  * -panel:shouldShowFilename: to be invoked. One situation in 
  * which this method would find use is whey you want the 
  * browser to show only files with certain extensions based on the 
  * selection made in an accessory-view pop-up list.  When the 
  * user changes the selection, you would invoke this method to
- * revalidate the visible columns. 
+ * revalidate the visible columns. </p>
  */
 - (void) validateVisibleColumns
 {
@@ -970,26 +972,26 @@ selectCellWithString: (NSString*)title
   return _canCreateDirectories;
 }
 
-/**
+/**<p>Shows the save panel for the user. This method invokes
- * Shows the save panel for the user. This method invokes
+  -runModalForDirectory:file: with empty strings for the filename.
- * -runModalForDirectory:file: with empty strings for the filename.
+  Returns NSOKButton (if the user clicks the OK button) or
- * Returns NSOKButton (if the user clicks the OK button) or
+  NSCancelButton (if the user clicks the Cancel button).</p>
- * NSCancelButton (if the user clicks the Cancel button).
+  <p>See Also: -runModalForDirectory:file:</p>
  */
 - (int) runModal
 {
   return [self runModalForDirectory: nil file: @""];
 }
 
-/**
+/**<p> Initializes the panel to the directory specified by path and,
- * Initializes the panel to the directory specified by path and,
+  optionally, the file specified by filename, then displays it and
- * optionally, the file specified by filename, then displays it and
+  begins its modal event loop; path and filename can be empty
- * begins its modal event loop; path and filename can be empty
+  strings.  The method invokes [NSApplication:-runModalForWindow:]
- * strings.  The method invokes [NSApplication:-runModalForWindow:]
+  method with self as the argument.  Returns NSOKButton (if the user
- * method with self as the argument.  Returns NSOKButton (if the user
+  clicks the OK button) or NSCancelButton (if the user clicks the
- * clicks the OK button) or NSCancelButton (if the user clicks the
+  Cancel button). If path is nil then the panel displays the last
- * Cancel button). If path is nil then the panel displays the last
+  selected directory or as a last resort, the current working directory.</p>
- * selected directory or as a last resort, the current working directory.
+  <p>See Also: -runModal</p>
  */
 - (int) runModalForDirectory: (NSString*)path file: (NSString*)filename
 {
@@ -1021,10 +1023,9 @@ selectCellWithString: (NSString*)title
 	 contextInfo: contextInfo];
 }
 
-/**
+/**<p> Returns the directory choosen by the user.  Do not invoke directory
- * Returns the directory choosen by the user.  Do not invoke directory
+   within a modal loop because the information that these methods
- * within a modal loop because the information that these methods
+   fetch is updated only upon return.</p><p>See Also: -setDirectory:</p>
- * fetch is updated only upon return.
  */
 - (NSString*) directory
 {
@@ -1034,10 +1035,9 @@ selectCellWithString: (NSString*)title
     return @"";
 }
 
-/**
+/**<p> Returns the absolute filename choosen by the user.  Do not invoke
- * Returns the absolute filename choosen by the user.  Do not invoke
+   filename within a modal loop because the information that these
- * filename within a modal loop because the information that these
+   methods fetch is updated only upon return.</p>
- * methods fetch is updated only upon return.
  */
 - (NSString*) filename
 {
@@ -1059,6 +1059,10 @@ selectCellWithString: (NSString*)title
   return [NSURL fileURLWithPath: [self filename]];
 }
 
+/**<p>Invoked by the 'Cancel' button. Saves the current directory browsed
+ and stop the modal event loop using [NSApplication-stopModalWithCode:]</p>
+ <p>See Also: -ok:</p>
+ */
 - (void) cancel: (id)sender
 {
   ASSIGN(_directory, [_browser pathToColumn:[_browser lastColumn]]);
@@ -1066,6 +1070,9 @@ selectCellWithString: (NSString*)title
   [self close];
 }
 
+/**<p>Invoked by the "OK" button. TODO </p>
+ *<p>See Also: -cancel:</p>
+ */
 - (void) ok: (id)sender
 {
   NSMatrix      *matrix;

Source/NSTextField.m

@@ -105,19 +105,25 @@ static Class textFieldCellClass;
   [super dealloc];
 }
 
-//
+/** <p>Returns whether the NSTextField is editable</p>
-// Setting User Access to Text
+    <p>See Also: -setEditable:</p>
-//
+*/
 - (BOOL) isEditable
 {
   return [_cell isEditable];
 }
 
+/** <p>Returns whether the NSTextField is selectable</p>
+    <p>See Also: -setSelectable:</p>
+*/
 - (BOOL) isSelectable
 {
   return [_cell isSelectable];
 }
 
+/** <p>Sets whether the NSTextField is editable</p>
+    <p>See Also: -isEditable</p>
+*/
 - (void) setEditable: (BOOL)flag
 {
   [_cell setEditable: flag];
@@ -125,6 +131,9 @@ static Class textFieldCellClass;
     [_text_object setEditable: flag];
 }
 
+/** <p>Sets whether the NSTextField is selectable</p>
+    <p>See Also: -isSelectable</p>
+*/
 - (void) setSelectable: (BOOL)flag
 {
   [_cell setSelectable: flag];
@@ -132,9 +141,8 @@ static Class textFieldCellClass;
     [_text_object setSelectable: flag];
 }
 
-//
+/**<p>Selects all the text inot the NSTextField if it's selectable.</p>
-// Editing Text
+ */
-//
 - (void) selectText: (id)sender
 {
   if ([self isSelectable] && (_super_view != nil))
@@ -143,18 +151,18 @@ static Class textFieldCellClass;
 	[_text_object selectAll: self];
       else
 	{
-	  NSText *t = [_window fieldEditor: YES  forObject: self];
+	  NSText *text = [_window fieldEditor: YES  forObject: self];
 	  int length;
 
-	  if ([t superview] != nil)
+	  if ([text superview] != nil)
-	    if ([t resignFirstResponder] == NO)
+	    if ([text resignFirstResponder] == NO)
 	      return;
 	  
 	  //  [NSCursor hide];
 	  /* [self stringValue] generates a call to validateEditing 
 	     so we need to call it before setting up the _text_object */
 	  length = [[self stringValue] length];
-	  _text_object = [_cell setUpFieldEditorAttributes: t];
+	  _text_object = [_cell setUpFieldEditorAttributes: text];
 	  [_cell selectWithFrame: _bounds
 		 inView: self
 		 editor: _text_object
@@ -188,9 +196,9 @@ static Class textFieldCellClass;
   [self setPreviousKeyView: anObject];
 }
 
-//
+/** <p>Sets the delegate to anObject</p>
-// Assigning a Delegate
+    <p>See Also: -delegate</p>
-//
+*/
 - (void) setDelegate: (id)anObject
 {
   if (_delegate)
@@ -208,59 +216,89 @@ static Class textFieldCellClass;
   SET_DELEGATE_NOTIFICATION(DidChange);
 }
 
+/** <p>Returns the delegate object</p>
+    <p>See Also: -setDelegate:</p>
+*/
 - (id) delegate
 {
   return _delegate;
 }
 
-//
+/** <p>Sets the color used to draw the background</p>
-// Modifying Graphic Attributes
+    <p>See Also: -backgroundColor</p>
-//
+ */
 - (void) setBackgroundColor: (NSColor *)aColor
 {
   [_cell setBackgroundColor: aColor];
 }
 
+/** <p>Returns the color used to draw the background</p>
+    <p>See Also: -setBackgroundColor:</p>
+ */
 - (NSColor *) backgroundColor
 {
   return [_cell backgroundColor];
 }
 
+/** <p>Returns whether the NSTextField draws the background</p>
+    <p>See Also: -setDrawsBackground:</p>
+ */
 - (BOOL) drawsBackground
 {
   return [_cell drawsBackground];
 }
 
+/** <p>Returns whether the NSTextField's cell has bezeled border</p>
+    <p>See Also: -setBezeled:</p>
+ */
 - (BOOL) isBezeled
 {
   return [_cell isBezeled];
 }
 
+/** <p>Returns whether the NSTextField's cell has border</p>
+    <p>See Also: -setBordered:</p>
+ */
 - (BOOL) isBordered
 {
   return [_cell isBordered];
 }
 
+/** <p>Sets whether the NSTextField's cell has bezeled border</p>
+    <p>See Also: -isBezeled</p>
+ */
 - (void) setBezeled: (BOOL)flag
 {
   [_cell setBezeled: flag];
 }
 
+/** <p>Sets whether the NSTextField's cell has border</p>
+    <p>See Also: -isBordered</p>
+ */
 - (void) setBordered: (BOOL)flag
 {
   [_cell setBordered: flag];
 }
 
+/** <p>Sets whether the NSTextField draws the background</p>
+    <p>See Also: -drawsBackground</p>
+ */
 - (void) setDrawsBackground: (BOOL)flag
 {
   [_cell setDrawsBackground: flag];
 }
 
+/** <p>Sets the  color with which the text will be draw to aColor</p>
+    <p>See Also: -textColor</p>
+ */
 - (void) setTextColor: (NSColor *)aColor
 {
   [_cell setTextColor: aColor];
 }
 
+/** <p>Returns the colour used to draw the text.</p>
+    <p>See Also: -setTextColor:</p>
+ */
 - (NSColor *) textColor
 {
   return [_cell textColor];

Source/NSTextFieldCell.m

@@ -128,11 +128,18 @@ static NSColor	*txtCol;
       [(NSControl *)_control_view updateCell: self];
 }
 
+/** <p>Returns the color used to draw the background</p>
+    <p>See Also: -setBackgroundColor:</p>
+ */
 - (NSColor *) backgroundColor
 {
   return _background_color;
 }
 
+
+/** <p>Sets whether the NSTextFieldCell draw its background color</p>
+    <p>See Also: -drawsBackground</p>
+ */
 - (void) setDrawsBackground: (BOOL)flag
 {
   _textfieldcell_draws_background = flag;
@@ -142,11 +149,17 @@ static NSColor	*txtCol;
       [(NSControl *)_control_view updateCell: self];
 }
 
+/** <p>Returns whether the NSTextFieldCell draw its background color</p>
+    <p>See Also: -setBackgroundColor:</p>
+ */
 - (BOOL) drawsBackground
 {
   return _textfieldcell_draws_background;
 }
 
+/** <p>Sets the text color to aColor</p>
+    <p>See Also: -textColor</p>
+ */
 - (void) setTextColor: (NSColor *)aColor
 {
   ASSIGN (_text_color, aColor);
@@ -155,6 +168,9 @@ static NSColor	*txtCol;
       [(NSControl *)_control_view updateCell: self];
 }
 
+/** <p>Returns the text color</p>
+    <p>See Also: -setTextColor:</p>
+ */
 - (NSColor *) textColor
 {
   return _text_color;