Improved documentation

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

Source/NSImage.m

@@ -192,6 +192,9 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
     }
 }
 
+/** <p>Returns the NSImage named aName. The search is done in the main bundle
+    first and then in the usual images directories</p>
+ */
 + (id) imageNamed: (NSString *)aName
 {
   NSString	*realName = [nsmapping objectForKey: aName];
@@ -310,7 +313,9 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   return [self initWithSize: NSMakeSize(0, 0)];
 }
 
-// Designated initializer for nearly everything.
+/** <p>Initialize and returns a new NSImage with <var>aSize</var> as specified
+    size.</p><p>See Also: -setSize: -size </p>
+ */
 - (id) initWithSize: (NSSize)aSize
 {
   [super init];
@@ -351,9 +356,15 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   return self;
 }
 
+
+/** <p>Initializes and returns a new NSImage from the file 
+    <var>fileName</var>. <var>fileName</var> should be an absolute path.</p>
+    <p>See Also: [NSImageRep+imageRepsWithContentsOfFile:]</p>
+ */
 - (id) initWithContentsOfFile: (NSString *)fileName
 {
-  self = [self init];
+  if ( ! ( self = [self init] ) )
+    return nil;
 
   _flags.dataRetained = YES;
   if (![self _loadFromFile: fileName])
@@ -365,9 +376,13 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   return self;
 }
 
+/**<p>Initializes and returns a new NSImage from the NSData data.</p>
+   <p>See Also: [NSImageRep+imageRepWithData:]</p>
+ */
 - (id) initWithData: (NSData *)data
 {
-  self = [self init];
+  if (! ( self = [self init] ) )
+    return nil;
 
   _flags.dataRetained = YES;
   if (![self _loadFromData: data])
@@ -425,10 +440,19 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   return self;
 }
 
+/** <p>Initializes and returns a new NSImage from the data in pasteboard.
+    the pasteboard types can be whose defined in  
+    [NSImageRep+imagePasteboardTypes] or NSFilenamesPboardType</p>
+    <p>See Also: [NSImageRep+imageRepsWithPasteboard:</p>
+ */
 - (id) initWithPasteboard: (NSPasteboard *)pasteboard
 {
-  NSArray *reps = [NSImageRep imageRepsWithPasteboard: pasteboard];
-  self = [self init];
+  NSArray *reps;
+
+  if ( ! ( self = [self init] ) )
+    return nil;
+  
+  reps = [NSImageRep imageRepsWithPasteboard: pasteboard];
 
   if (reps != nil)
     [self addRepresentations: reps]; 
@@ -524,6 +548,10 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   return _name;
 }
 
+/** <p>Sets the NSImage size to aSize. Changing the size recreate
+    the cache</p>
+    <p>See Also: -size -initWithSize:</p>
+ */
 - (void) setSize: (NSSize)aSize
 {
   // Optimized as this is called very often from NSImageCell
@@ -536,6 +564,10 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   [self recache];
 }
 
+/**<p> Returns NSImage size if the size have been set. Returns the
+   size of the best representation otherwise.</p>
+   <p>See Also: -setSize: -initWithSize:</p>
+ */
 - (NSSize) size
 {
   if (_size.width == 0) 
@@ -683,6 +715,9 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   return _flags.scalable;
 }
 
+/**<p>Sets the color of the NSImage's background to <var>aColor</var></p>
+   <p>See Also: -backgroundColor</p>
+ */
 - (void) setBackgroundColor: (NSColor *)aColor
 {
   if (aColor == nil)
@@ -692,6 +727,9 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   ASSIGN(_color, aColor);
 }
 
+/**<p>Returns the color of the NSImage's background</p>
+   <p>See Also: -setBackgroundColor:</p>
+ */
 - (NSColor *) backgroundColor
 {
   return _color;
@@ -1122,6 +1160,10 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   }
 }
 
+/** <p>Adds the NSImageRep imageRep to the NSImage's representations array.
+    </p><p>See Also: -addRepresentations: removeRepresentation:</p>
+ */
+
 - (void) addRepresentation: (NSImageRep *)imageRep
 {
   GSRepData	*repd;
@@ -1132,6 +1174,10 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
   RELEASE(repd);
 }
 
+/** <p>Adds the NSImageRep array imageRepArray to the NSImage's
+    representations array.</p>
+    <p>See Also: -addRepresentation: -removeRepresentation:</p>
+ */
 - (void) addRepresentations: (NSArray *)imageRepArray
 {
   unsigned	i, count;
@@ -1147,6 +1193,9 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
     }
 }
 
+/** <p>Remove the NSImageRep imageRep from the NSImage's representations 
+    array</p><p>See Also: -addRepresentations: -addRepresentation:</p>
+ */
 - (void) removeRepresentation: (NSImageRep *)imageRep
 {
   unsigned	i;
@@ -1167,11 +1216,17 @@ repd_for_rep(NSArray *_reps, NSImageRep *rep)
     }
 }
 
+/** <p>Locks the focus on the best representation</p>
+    <p>See Also: -lockFocusOnRepresentation:</p>
+ */
 - (void) lockFocus
 {
   [self lockFocusOnRepresentation: nil];
 }
 
+/**<p>Locks the focus in the imageRep. if imageRep is nil this method
+   locks the focus on the best representation</p>
+ */
 - (void) lockFocusOnRepresentation: (NSImageRep *)imageRep
 {
   if (_cacheMode != NSImageCacheNever)