Improved docuentation

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

ChangeLog

@@ -1,3 +1,9 @@
+2005-12-04  Fabien VALLON  <fabien@sonappart.net>
+
+	* Source/NSColorPanel.m: Improved documentation, various cleanups
+	* Source/NSColor.m: Improved documentation
+	* Source/NSClipView.m: Improved documentation
+
 2005-12-04  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/GSServicesManager.m: Implement use of NSUseRunningCopy

Source/NSClipView.m

@@ -118,7 +118,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view)
 
 
 /**<p>Sets aView the NSClipView's document view to <var>aView</var>
-   .TODO explain notifications ... </p>
+   </p>
    <p>See Also: -documentView</p>
  */
 - (void) setDocumentView: (NSView*)aView
@@ -368,7 +368,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view)
 }
 
 /**
- *<p>TODO</p>
+ *<p></p>
  */
 - (NSPoint) constrainScrollPoint: (NSPoint)proposedNewOrigin
 {
@@ -462,8 +462,9 @@ static inline NSRect integralRect (NSRect rect, NSView *view)
   return rect;
 }
 
-/**<p>Returns the document visible rectangle</p>
+/**<p>Returns the document visible rectangle. Returns NSZeroRect if the 
- <p>See Also: -documentRect </p>
+   document view does not exists.</p>
+ <p>See Also: -documentRect [NSView-convertRect:toView:]</p>
  */
 - (NSRect) documentVisibleRect
 {
@@ -492,7 +493,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view)
     }
 }
 
-/**<p>Scrolls in response to mouse-dragged events.</p>
+/**<p>Scrolls in response to mouse-dragged events. </p>
  */
 - (BOOL) autoscroll: (NSEvent*)theEvent
 {
@@ -599,7 +600,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view)
 }
 
 /**
- *<p>Returns the NSClipView's document view</p>
+ *<p>Returns the NSClipView's document view.</p>
  *<p>See Also: -setDocumentView: </p>
  */
 - (id) documentView
@@ -607,11 +608,15 @@ static inline NSRect integralRect (NSRect rect, NSView *view)
   return _documentView;
 }
 
+/**
+ */
 - (void) setCopiesOnScroll: (BOOL)flag
 {
   _copiesOnScroll = flag;
 }
 
+/**
+ */
 - (BOOL) copiesOnScroll
 {
   return _copiesOnScroll;
@@ -642,7 +647,10 @@ static inline NSRect integralRect (NSRect rect, NSView *view)
 }
 
 /**<p>Sets the NSClipView's background color to <var>aColor</var> and marks
-   self for display. Sets the opaque flag to if needed</p> 
+   self for display. Sets the opaque flag if needed ( to YES if the
+   NSClipView does not draw its background, if the background color
+   is nil or if the background color alpha component is less than 1.0 , NO
+   otherwise) </p> 
    <p>See Also: -backgroundColor [NSView-isOpaque]</p>
  */
 - (void) setBackgroundColor: (NSColor*)aColor

Source/NSColor.m

@@ -649,7 +649,7 @@ systemColorWithName(NSString *name)
 }
 
 
-/** TODO
+/** Returns whether TODO
  *<p>See Also: +setIgnoresAlpha:</p>
  */
 + (BOOL) ignoresAlpha
@@ -866,10 +866,9 @@ systemColorWithName(NSString *name)
   return nil;
 }
 
-/**
+/**<p>Gets the cyan, magenta, yellow,black and alpha values from the NSColor.
- *<p>Returns CYMK and alpha values.
+ Raises a NSInternalInconsistencyException if the NSColor is not a CYMK color
- * GNUstep implemenation raise an NSInternalInconsistencyException</p>
+ </p>
- *
  */
 - (void) getCyan: (float*)cyan
 	 magenta: (float*)magenta
@@ -881,6 +880,10 @@ systemColorWithName(NSString *name)
     format: @"Called getCyan:magenta:yellow:black:alpha: on non-CMYK colour"];
 }
 
+/**<p>Gets the hue, saturation, brightness and alpha values from the NSColor.
+ Raises a NSInternalInconsistencyException if the NSColor is not a RGB color
+ </p>
+ */
 - (void) getHue: (float*)hue
      saturation: (float*)saturation
      brightness: (float*)brightness
@@ -890,7 +893,11 @@ systemColorWithName(NSString *name)
     format: @"Called getHue:saturation:brightness:alpha: on non-RGB colour"];
 }
 
-- (void) getRed: (float*)red
+/**<p>Gets the red, green, blue and alpha values from the NSColor.
+ Raises a NSInternalInconsistencyException if the NSColor is not a RGB color
+ </p>
+ */
+-(void) getRed: (float*)red
 	  green: (float*)green
 	   blue: (float*)blue
 	  alpha: (float*)alpha
@@ -899,6 +906,10 @@ systemColorWithName(NSString *name)
 	      format: @"Called getRed:green:blue:alpha: on non-RGB colour"];
 }
 
+/**<p>Gets the white alpha values from the NSColor.
+ Raises a NSInternalInconsistencyException if the NSColor is not a 
+ greyscale color</p>
+ */
 - (void) getWhite: (float*)white
 	    alpha: (float*)alpha
 {
@@ -919,13 +930,16 @@ systemColorWithName(NSString *name)
     }
 }
 
-/** <p>Returns the alpha component (1.0 by default) </p>
+/** <p>Returns the alpha component. </p>
  */
 - (float) alphaComponent
 {
   return 1.0;
 }
 
+/** <p>Returns the black component. Raises a NSInternalInconsistencyException
+    if NSColor is not a CMYK color.</p>
+ */
 - (float) blackComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -933,6 +947,9 @@ systemColorWithName(NSString *name)
   return 0.0;
 }
 
+/** <p>Returns the blue component. Raises a NSInternalInconsistencyException
+    if NSColor is not a RGB color.</p>
+ */
 - (float) blueComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -940,6 +957,9 @@ systemColorWithName(NSString *name)
   return 0.0;
 }
 
+/** <p>Returns the brightness component. Raises a 
+    NSInternalInconsistencyException if NSColor space is not a RGB color</p>
+*/
 - (float) brightnessComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -961,6 +981,9 @@ systemColorWithName(NSString *name)
   return nil;
 }
 
+/** <p>Returns the cyan component. Raises a  NSInternalInconsistencyException 
+    if NSColor is not a CYMK color</p>
+*/
 - (float) cyanComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -968,6 +991,9 @@ systemColorWithName(NSString *name)
   return 0.0;
 }
 
+/** <p>Returns the green component. Raises a  NSInternalInconsistencyException 
+    if NSColor is not a RGB color</p>
+*/
 - (float) greenComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -975,6 +1001,9 @@ systemColorWithName(NSString *name)
   return 0.0;
 }
 
+/** <p>Returns the hue component. Raises a  NSInternalInconsistencyException 
+    if NSColor is not a RGB color</p>
+*/
 - (float) hueComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -996,6 +1025,9 @@ systemColorWithName(NSString *name)
   return nil;
 }
 
+/** <p>Returns the magenta component. Raises a  
+    NSInternalInconsistencyException  if NSColor is not a CMYK color</p>
+*/
 - (float) magentaComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -1003,6 +1035,9 @@ systemColorWithName(NSString *name)
   return 0.0;
 }
 
+/** <p>Returns the red component. Raises a NSInternalInconsistencyException  
+    if NSColor is not a RGB color</p>
+*/
 - (float) redComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -1010,6 +1045,9 @@ systemColorWithName(NSString *name)
   return 0.0;
 }
 
+/** <p>Returns the saturation component. Raises a
+    NSInternalInconsistencyException if NSColor is not a RGB color</p>
+*/
 - (float) saturationComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -1017,6 +1055,9 @@ systemColorWithName(NSString *name)
   return 0.0;
 }
 
+/** <p>Returns the white component. Raises a NSInternalInconsistencyException  
+    if NSColor is not a grayscale color</p>
+*/
 - (float) whiteComponent
 {
   [NSException raise: NSInternalInconsistencyException
@@ -1031,6 +1072,9 @@ systemColorWithName(NSString *name)
   return nil;
 }
 
+/** <p>Returns the yellow component. Raises a NSInternalInconsistencyException
+    if NSColor is not a RGB color</p>
+*/
 - (float) yellowComponent
 {
   [NSException raise: NSInternalInconsistencyException

Source/NSColorPanel.m

@@ -411,32 +411,40 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel;
   _gs_gui_color_picker_mask = mask;
 }
 
+/**
+ */
 + (void) setPickerMode: (int)mode
 {
   _gs_gui_color_picker_mode = mode;
 }
 
+/**<p>Drags <var>aColor</var> frome <var>sourceView</var> at the location
+   give by the event <var>anEvent</var> ( [NSView-convertPoint:fromView:] ).
+   The type declare into the pasteboard is NSColorPboardType</p>
+   <p>See Also: [NSView-convertPoint:fromView:] 
+   [NSView-dragImage:at:offset:event:pasteboard:source:slideBack:</p>
+ */
 + (BOOL) dragColor: (NSColor *)aColor
 	 withEvent: (NSEvent *)anEvent
 	  fromView: (NSView *)sourceView
 {
   NSPasteboard	*pb = [NSPasteboard pasteboardWithName: NSDragPboard];
   NSImage	*image = [NSImage imageNamed: @"common_ColorSwatch"];
-  NSSize	s;
+  NSSize	size;
-  NSPoint	p;
+  NSPoint	point;
 
   [pb declareTypes: [NSArray arrayWithObjects: NSColorPboardType, nil]
-             owner: aColor];
+      owner: aColor];
   [aColor writeToPasteboard: pb];
   [image setBackgroundColor: aColor];
 
-  s = [image size];
+  size = [image size];
-  p = [sourceView convertPoint: [anEvent locationInWindow] fromView: nil];
+  point = [sourceView convertPoint: [anEvent locationInWindow] fromView: nil];
-  p.x -= s.width/2;
+  point.x -= size.width/2;
-  p.y -= s.width/2;
+  point.y -= size.width/2;
 
   [sourceView dragImage: image
-                     at: p
+                     at: point
                  offset: NSMakeSize(0,0)
                   event: anEvent
              pasteboard: pb
@@ -530,7 +538,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel;
 /**<p>Sets the NSColorPanl action method to <var>aSelector</var> The
    action message is usally send in -setColor:, when the picker is updated,
    when a new picker is show, when the alpha is changed or when one of the
-   color well at the bottom is selected</p>
+   color well at the bottom is selected.</p>
  */
 - (void) setAction: (SEL)aSelector
 {
@@ -545,7 +553,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel;
   _isContinuous = flag;
 }
 
-/** <p>Set the NSColorPanel mode to mode. TODO more about _pickers</p>
+/** <p>Set the NSColorPanel mode to <var>mode</var>.</p>
     <p>See Also: -mode</p>
  */
 - (void) setMode: (int)mode
@@ -569,7 +577,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel;
 }
 
 /** <p>Sets whether the NSColorPanel shows alpha values and the alpha
-    slider</p><p>See Also: -showsAlpha</p>
+    slider.</p><p>See Also: -showsAlpha</p>
  */
 - (void) setShowsAlpha: (BOOL)flag
 {
@@ -633,9 +641,10 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel;
                             withObject: aColorList];
 }
 
-//
+/** <p>Returns the alpha value of the NSColorPanel. Returns
-// Setting Color
+    1.0 if the NSColorPanel does not show alpha</p>
-//
+    <p>See Also: -showsAlpha -setShowsAlpha:</p>    
+ */
 - (float) alpha
 {
   if ([self showsAlpha])
@@ -644,7 +653,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel;
     return 1.0;
 }
 
-/** <p>Returns the current NSColor displayed by the NSColorPanel</p>
+/** <p>Returns the current NSColor displayed by the NSColorPanel.</p>
     <p>See Also : -setColor:</p>
  */
 - (NSColor *) color
@@ -653,8 +662,9 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel;
 }
 
 /** <p>Sets the NSColor displayed to aColor. This method post a
-    NSColorPanelColorChangedNotification notification</p>
+    NSColorPanelColorChangedNotification notification if needed.</p>
-    <p>See Also: -color</p>
+    <p>See Also: -color [NSColorWell-setColor:]
+    </p>
 */
 - (void) setColor: (NSColor *)aColor
 {