Improved documentation

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

Source/NSButton.m

@@ -58,7 +58,7 @@ static id buttonCellClass = nil;
 //
 // Initializing the NSButton Factory
 //
-/**
+/** Returns 
    
  */
 + (Class) cellClass
@@ -80,9 +80,10 @@ static id buttonCellClass = nil;
   return YES;
 }
 
-//
+/** <p>Sets the NSButtonCell's type to <var>aType</var> and marks self for
-// Setting the Button Type
+    display.See <ref type="type" id="NSButtonType">NSButtonType</ref> for more
-//
+    informations.</p>
+ */
 - (void) setButtonType: (NSButtonType)aType
 {
   [_cell setButtonType: aType];
@@ -117,8 +118,9 @@ static id buttonCellClass = nil;
   [self setState: (aDouble != 0)];
 }
 
-/** <p>Sets the NSButtonCell's state to value and marks self for display</p>
+/**<p>Sets the NSButtonCell's state to <var>value</var> and marks
-   <p>See Also: -state</p>  */
+   self for display.</p><p>See Also: -state</p> 
+ */
 - (void) setState: (int)value
 {
   [_cell setState: value];
@@ -142,6 +144,9 @@ static id buttonCellClass = nil;
   [_cell setAllowsMixedState: flag];
 }
 
+/**<p>Sets the NSButtonCell to the next state and marks self for display.</p>
+   <p>See Also: [NSButtonCell-setNextState]</p>
+ */
 - (void)setNextState
 {
   [_cell setNextState];
@@ -163,18 +168,16 @@ static id buttonCellClass = nil;
   [_cell setPeriodicDelay: delay interval: interval];
 }
 
-//
+/**<p>Returns the NSButtonCell's alternate title</p>
-// Setting the Titles
+   <p>See Also: -setAlternateTitle:</p>
-//
-/** <p>Returns the NSButtonCell's title</p><p>See Also: -setAlternateTitle:</p>
  */
 - (NSString *) alternateTitle
 {
   return [_cell alternateTitle];
 }
 
-/** <p>Sets the NSButtonCell's alternateTitle to aString and marks the view
+/**<p>Sets the NSButtonCell's alternateTitle to aString and marks self
-    for display</p><p>See Also: -alternateTitle</p>
+   for display</p><p>See Also: -alternateTitle</p>
  */
 - (void) setAlternateTitle: (NSString *)aString
 {
@@ -182,8 +185,8 @@ static id buttonCellClass = nil;
   [self setNeedsDisplay: YES];
 }
 
-/** <p>Sets the NSButtonCell's title to aString and marks the view for display
+/**<p>Sets the NSButtonCell's title to aString and marks self for display
-    </p><p>See Also: -title</p>
+   </p><p>See Also: -title</p>
  */
 - (void) setTitle: (NSString *)aString
 {
@@ -229,7 +232,7 @@ static id buttonCellClass = nil;
 //
 // Setting the Images
 //
-/** <p>Returns the NSButtonCell's alternate image</p>
+/** <p>Returns the NSButtonCell's alternate image.</p>
     <p>See Also: -setAlternateImage:</p> 
 */
 - (NSImage *) alternateImage
@@ -238,17 +241,18 @@ static id buttonCellClass = nil;
 }
 
 /** <p>Returns the NSButtonCell's image</p>
-    <p>See Also: -setImage:</p> */
+    <p>See Also: -setImage:</p> 
+*/
 - (NSImage *) image
 {
   return [_cell image];
 }
 
 /** <p>Returns the position of the NSButtonCell's image. See 
-    NSCellImagePosition for more informations </p>
+    <ref type="type" id="NSCellImagePosition">NSCellImagePosition</ref>
+    for more informations. </p>
     <p>See Also: -setImagePosition:</p> 
 */
-
 - (NSCellImagePosition) imagePosition
 {
   return [_cell imagePosition];
@@ -264,7 +268,7 @@ static id buttonCellClass = nil;
 }
 
 /** <p>Sets the NSButtonCell's image to anImage and marks self
-    for display</p><p>See Also: -image </p>
+    for display.</p><p>See Also: -image </p>
 */
 - (void) setImage: (NSImage *)anImage
 {
@@ -273,7 +277,9 @@ static id buttonCellClass = nil;
 }
 
 /** <p>Sets the postion of the NSButtonCell's image to aPosition
-    and marks self for display</p><p>See Also: -imagePosition </p>
+    and marks self for display. See <ref type="type" id="NSCellImagePosition">
+    NSCellImagePosition</ref>for more informations.</p>
+    <p>See Also: -imagePosition </p>
 */
 - (void) setImagePosition: (NSCellImagePosition)aPosition
 {
@@ -284,24 +290,25 @@ static id buttonCellClass = nil;
 //
 // Modifying Graphic Attributes
 //
-/** <p>Returns whether the NSButtonCell has border</p>
+/** <p>Returns whether the NSButton's cell has border. 
-    <p>See Also: -setBordered:</p>
+    </p><p>See Also: -setBordered:</p>
 */
 - (BOOL) isBordered
 {
   return [_cell isBordered];
 }
 
-/** <p>Returns whether the NSButtonCell is transparent</p>
+/** <p>Returns whether the NSButton's cell is transparent</p>
-    <p>See Also: -setBordered:</p>
+    <p>See Also: -setTransparent:</p>
 */
 - (BOOL) isTransparent
 {
   return [_cell isTransparent];
 }
 
-/** <p>Sets whether the NSButtonCell has border and marks self for 
+/** <p>Sets whether the NSButton's cell has border and marks self for 
-    display</p><p>See Also: -isBordered</p>
+    display.</p>
+    <p>See Also: -isBordered</p>
 */
 - (void) setBordered: (BOOL)flag
 {
@@ -309,7 +316,7 @@ static id buttonCellClass = nil;
   [self setNeedsDisplay: YES];
 }
 
-/** <p>Sets whether the NSButtonCell is transparent and marks self for 
+/** <p>Sets whether the NSButton's cell is transparent and marks self for 
     display</p><p>See Also: -isTransparent</p>
 */
 - (void) setTransparent: (BOOL)flag
@@ -318,18 +325,18 @@ static id buttonCellClass = nil;
   [self setNeedsDisplay: YES];
 }
 
-/** <p>Returns the style of the NSButtonCell's bezeled border. See NSBezelStyle
+/** <p>Returns the style of the NSButtonCell's bezeled border. 
-    for more informations</p>
+    See <ref type="type" id="NSBezelStyle">NSBezelStyle</ref> for more
-    <p>See Also: -setBezelStyle:</p>
+    informations</p><p>See Also: -setBezelStyle:</p>
 */
 - (NSBezelStyle)bezelStyle
 {
   return [_cell bezelStyle];
 }
 
-/** <p>Sets the style of the NSButtonCell's bezeled border and marks self for
+/**<p>Sets the style of the NSButtonCell's bezeled border and marks self for
-    display. See NSBezelStyle for more informations</p>
+   display. See <ref type="type" id="NSBezelStyle">NSBezelStyle</ref>
-    <p>See Also: -bezelStyle</p>
+   for more informations</p> <p>See Also: -bezelStyle</p>
 */
 - (void)setBezelStyle:(NSBezelStyle)bezelStyle
 {
@@ -361,9 +368,8 @@ static id buttonCellClass = nil;
 //
 // Setting the Key Equivalent
 //
-/** <p>Returns the NSButtonCell's key equivalent. This is used in
+/**<p>Returns the NSButtonCell's key equivalent. This is used in
-   -performKeyEquivalent: ... TODO</p>
+   -performKeyEquivalent: ... TODO</p><p>See Also: -setKeyEquivalent:</p>
-   <p>See Also: -setKeyEquivalent:</p>
  */
 - (NSString*) keyEquivalent
 {
@@ -380,8 +386,7 @@ static id buttonCellClass = nil;
 }
 
 /** <p>Sets the NSButtonCell's key equivalent.This is used in
-   -performKeyEquivalent: ... TODO</p>
+    -performKeyEquivalent: </p> <p>See Also: -keyEquivalent</p>
-   <p>See Also: -keyEquivalent</p>
 */
 - (void) setKeyEquivalent: (NSString*)aKeyEquivalent
 {
@@ -389,7 +394,7 @@ static id buttonCellClass = nil;
 }
 
 /** <p>Sets the modifier mask of the NSButtonCell's key equivalent.
-    This is used in   -performKeyEquivalent: ... TODO</p>
+    This is used in -performKeyEquivalent:</p>
    <p>See Also: -keyEquivalentModifierMask</p>
 */
 - (void) setKeyEquivalentModifierMask: (unsigned int)mask

Source/NSButtonCell.m

@@ -129,31 +129,35 @@
   [super dealloc];
 }
 
-
+/** 
+ *<p>The GNUstep implementation does nothing here
+ *  (to match the Mac OS X behavior) because with
+ * NSButtonCell GNUstep implementation the cell type is bound to the image
+ * position. We implemented this behavior because it permits to have
+ * -setFont: -setTitle -setImage: methods which are symetrical by not altering
+ * directly the cell type and to validate the fact that the cell type is more
+ * characterized by the potential visibility of the image (which is under the
+ * control of the method -setImagePosition:) than by the value of the image
+ * ivar itself (related to -setImage: method).  
+ * On Mac OS X, the NSButtonCell cell type is NSTextCellType by default or
+ * NSImageCellType if the initialization has been done with -initImageCell:,
+ * it should be noted that the cell type never changes later.</p>
+ */
 - (void) setType: (NSCellType)aType
 {
-  /* We do nothing here (we match the Mac OS X behavior) because with
-   * NSButtonCell GNUstep implementation the cell type is bound to the image
-   * position. We implemented this behavior because it permits to have
-   * -setFont: -setTitle -setImage: methods which are symetrical by not altering
-   * directly the cell type and to validate the fact that the cell type is more
-   * characterized by the potential visibility of the image (which is under the
-   * control of the method -setImagePosition:) than by the value of the image
-   * ivar itself (related to -setImage: method).  
-   * On Mac OS X, the NSButtonCell cell type is NSTextCellType by default or
-   * NSImageCellType if the initialization has been done with -initImageCell:,
-   * it should be noted that the cell type never changes later.
-   */
 }
 
-/*
+/** <p>Returns the NSButtonCell's title</p>
- * Setting the Titles
+    <p>See Also: -setTitle: [NSCell-stringValue]</p>
  */
 - (NSString*) title
 {
   return [self stringValue];
 }
 
+/** <p>Returns the NSButtonCell's alternate title ( used when highlighted )</p>
+    <p>See Also: -setAlternateTitle:</p>
+ */
 - (NSString*) alternateTitle
 {
   return _altContents;
@@ -265,11 +269,18 @@
     }
 }
 
+/** <p>Sets the NSButtonCell's title to <var>aString</var></p>
+    <p>See Also: -title [NSCell-setStringValue:]</p>
+ */
 - (void) setTitle: (NSString*)aString
 {
   [self setStringValue: aString];
 }
 
+/** <p>Sets the NSButtonCell's alternate title ( used when highlighted ) 
+    to <var>aString</var> and update the cell if it contains 
+    a NSControl view</p><p>See Also: -alternateTitle</p>
+ */
 - (void) setAlternateTitle: (NSString*)aString
 {
   ASSIGNCOPY(_altContents, aString);
@@ -350,14 +361,18 @@
   [self setAlternateMnemonicLocation: location];
 }
 
-/*
+/**<p>Returns the NSButtonCell's alternate image</p>
- * Setting the Images
+   <p>See Also: -setAlternateImage:</p> 
  */
 - (NSImage*) alternateImage
 {
   return _altImage;
 }
 
+/** <p>Returns the NSButtonCell's image position. See <ref type="type" 
+    id="NSCellImagePosition">NSCellImagePosition</ref> for more informations.
+    </p><p>See Also: -setImagePosition:</p>
+ */
 - (NSCellImagePosition) imagePosition
 {
   return _cell.image_position;
@@ -384,6 +399,12 @@
   ASSIGN(_altImage, anImage);
 }
 
+/**<p>Sets the image position. The GNUstep implementation depends only on 
+ *the image position. If the image position is set to NSNoImage
+ * then the type is set to NSTextCellType, to NSImageCellType otherwise</p>
+ *<p>See Also: -imagePosition</p>
+ *
+ */
 - (void) setImagePosition: (NSCellImagePosition)aPosition
 {
   _cell.image_position = aPosition;
@@ -416,14 +437,19 @@
   _repeatInterval = interval;
 }
 
-/*
+/**<p>Returns the key equivalent. 
- * Setting the Key Equivalent
+   The key equivalent is used into the [NSButton-performKeyEquivalent:] method
+   ( subclass of NSResponder ) </p>
+   <p>See Also: -setKeyEquivalent: [NSButton-performKeyEquivalent:]</p>
  */
 - (NSString*) keyEquivalent
 {
   return _keyEquivalent;
 }
 
+/**<p>Returns the NSFont of the key equivalent ( TODO explain )</p>
+ *<p>See Also: -setKeyEquivalentFont:</p>
+ */
 - (NSFont*) keyEquivalentFont
 {
   return _keyEquivalentFont;
@@ -434,16 +460,29 @@
   return _keyEquivalentModifierMask;
 }
 
+/**<p>Sets the key equivalent.The key equivalent is used into the
+  [NSButton-performKeyEquivalent:] method ( subclass of NSResponder )</p>
+ <p>See Also: -keyEquivalent -setKeyEquivalentModifierMask:
+ -keyEquivalentModifierMask</p>
+*/
 - (void) setKeyEquivalent: (NSString*)key
 {
   ASSIGNCOPY(_keyEquivalent, key);
 }
 
+/**<p>Sets the mask ( modifier key ) for the keyEquivalent.The key equivalent 
+ *is used into the [NSButton-performKeyEquivalent:] method 
+ *( subclass of NSResponder )</p>
+ *<p>See Also: -keyEquivalentModifierMask keyEquivalent -setKeyEquivalent:</p>
+ */
 - (void) setKeyEquivalentModifierMask: (unsigned int)mask
 {
   _keyEquivalentModifierMask = mask;
 }
 
+/**<p>Sets the NSFont of the key equivalent. TODO explain </p>
+ *<p>See Also: -keyEquivalentFont</p>
+ */
 - (void) setKeyEquivalentFont: (NSFont*)fontObj
 {
   ASSIGN(_keyEquivalentFont, fontObj);
@@ -454,19 +493,25 @@
   ASSIGN(_keyEquivalentFont, [NSFont fontWithName: fontName size: fontSize]);
 }
 
-/*
+/**<p>Returns whether the button cell is transparent </p>
- * Modifying Graphic Attributes
+ *<p>See Also: -setTransparent:</p>
  */
 - (BOOL) isTransparent
 {
   return _buttoncell_is_transparent;
 }
 
+/**<p>Sets whether the button cell is transparent</p>
+ *<p>See Also: -isTransparent </p>
+ */
 - (void) setTransparent: (BOOL)flag
 {
   _buttoncell_is_transparent = flag;
 }
 
+/**<p>Returns whether the NSButtonCell is opaque. Returns YES if the button 
+   cell is not transparent and if the cell is bordered. NO otherwise</p>
+ */
 - (BOOL) isOpaque
 {
   return !_buttoncell_is_transparent && _cell.is_bordered;