Lots of documentation added.

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

ChangeLog

@@ -2,8 +2,8 @@
 
 	* Source/NSObject.m: Change NSDecrementExtraRefCountWasZero() to
 	refrain from decrementing when the count is zero.  Documented
-	the retain/release/retainCopunt methods.
+	the retain/release/retainCount methods (and others).
-	* headers/Foundation/NSObject.h: Documented extra ref count functions.
+	* Headers/Foundation/NSObject.h: Documented extra ref count functions.
 
 2002-05-28  Richard Frith-Macdonald <rfm@gnu.org>
 

Headers/gnustep/base/GSMime.h

@@ -1,5 +1,5 @@
 
-/* Interface for MIME parsing classes
+/** Interface for MIME parsing classes
 
    Copyright (C) 2000 Free Software Foundation, Inc.
 

Headers/gnustep/base/NSObject.h

@@ -103,57 +103,91 @@
 + (void) initialize;
 + (id) allocWithZone: (NSZone*)z;
 + (id) alloc;
-+ (id) new;
-- (id) copy;
-- (void) dealloc;
-- (id) init;
-- (id) mutableCopy;
-
 + (Class) class;
-+ (Class) superclass;
-
-+ (BOOL) instancesRespondToSelector: (SEL)aSelector;
-
-+ (IMP) instanceMethodForSelector: (SEL)aSelector;
-- (IMP) methodForSelector: (SEL)aSelector;
-+ (NSMethodSignature*) instanceMethodSignatureForSelector: (SEL)aSelector;
-- (NSMethodSignature*) methodSignatureForSelector: (SEL)aSelector;
-
-- (NSString*) description;
 + (NSString*) description;
-
++ (IMP) instanceMethodForSelector: (SEL)aSelector;
++ (NSMethodSignature*) instanceMethodSignatureForSelector: (SEL)aSelector;
++ (BOOL) instancesRespondToSelector: (SEL)aSelector;
++ (id) new;
 + (void) poseAsClass: (Class)aClassObject;
++ (id) setVersion: (int)aVersion;
++ (Class) superclass;
++ (int) version;
 
-- (void) doesNotRecognizeSelector: (SEL)aSelector;
+- (id) autorelease;
-
-- (void) forwardInvocation: (NSInvocation*)anInvocation;
-
 - (id) awakeAfterUsingCoder: (NSCoder*)aDecoder;
+- (Class) class;
 - (Class) classForArchiver;
 - (Class) classForCoder;
 - (Class) classForPortCoder;
+- (BOOL) conformsToProtocol: (Protocol *)aProtocol;
+- (id) copy;
+- (void) dealloc;
+- (NSString*) description;
+- (void) doesNotRecognizeSelector: (SEL)aSelector;
+- (void) forwardInvocation: (NSInvocation*)anInvocation;
+- (unsigned) hash;
+- (id) init;
+- (BOOL) isEqual: anObject;
+- (BOOL) isKindOfClass: (Class)aClass;
+- (BOOL) isMemberOfClass: (Class)aClass;
+- (BOOL) isProxy;
+- (IMP) methodForSelector: (SEL)aSelector;
+- (NSMethodSignature*) methodSignatureForSelector: (SEL)aSelector;
+- (id) mutableCopy;
+- (id) performSelector: (SEL)aSelector;
+- (id) performSelector: (SEL)aSelector withObject: anObject;
+- (id) performSelector: (SEL)aSelector withObject: object1 withObject: object2;
+- (void) release;
 - (id) replacementObjectForArchiver: (NSArchiver*)anArchiver;
 - (id) replacementObjectForCoder: (NSCoder*)anEncoder;
 - (id) replacementObjectForPortCoder: (NSPortCoder*)aCoder;
-
+- (BOOL) respondsToSelector: (SEL)aSelector;
-
+- (id) retain;
-+ (id) setVersion: (int)aVersion;
+- (unsigned) retainCount;
-+ (int) version;
+- (id) self;
-
+- (Class) superclass;
+- (NSZone*) zone;
 @end
 
+/**
+ * Used to allocate memory to hold an object, and initialise the
+ * class of the object to be aClass etc.  The allocated memory will
+ * be extraBytes larger than the space actually needed to hold the
+ * instance variables of the object.<br />
+ * This function is used by the [NSObject-allocWithZone:] mnethod.
+ */
 GS_EXPORT NSObject *
 NSAllocateObject(Class aClass, unsigned extraBytes, NSZone *zone);
+
+/**
+ * Used to release the memory used by an object.<br />
+ * This function is used by the [NSObject-dealloc] mnethod.
+ */
 GS_EXPORT void
 NSDeallocateObject(NSObject *anObject);
+
+/**
+ * Used to copy anObject.  This makes a bitwise copy of anObject to
+ * memory allocated from zone.  The allocated memory will be extraBytes
+ * longer than that necessary to actually store the instance variables
+ * of the copied object.<br />
+ * This is used by the [NSObject-copyWithZone:] method.
+ */
 GS_EXPORT NSObject *
 NSCopyObject(NSObject *anObject, unsigned extraBytes, NSZone *zone);
 
+/**
+ * Returns a flag to indicate whether anObject should be retained or
+ * copied in order to make a copy in the specified zone.<br />
+ * Basically, this tests to see if anObject was allocated from
+ * requestedZone and returns YES if it was.
+ */
 GS_EXPORT BOOL
 NSShouldRetainWithZone(NSObject *anObject, NSZone *requestedZone);
 
 /**
- * Return the extra reference count of anObject.  The reference count
+ * Return the extra reference count of anObject.  The retain count
  * for an object is this value plus one.
  */
 GS_EXPORT unsigned
@@ -161,7 +195,7 @@ NSExtraRefCount(id anObject);
 
 /**
  * Increment the extra reference count for anObject.  This is used
- * by the -retain method.
+ * by the [NSObject-retain] method.
  */
 GS_EXPORT void
 NSIncrementExtraRefCount(id anObject);
@@ -169,7 +203,8 @@ NSIncrementExtraRefCount(id anObject);
 /**
  * Examines the extra reference count for the object and, if non-zero
  * decrements it.  Returns a flag to say whether the count was zero
- * (and hence whether the extra refrence count was decremented).
+ * (and hence whether the extra refrence count was decremented).<br />
+ * This us used by the [NSObject-release] method.
  */
 GS_EXPORT BOOL
 NSDecrementExtraRefCountWasZero(id anObject);

Source/Additions/GSMime.m

@@ -2698,7 +2698,7 @@ static NSCharacterSet	*tokenSet = nil;
 /**
  * Adds a part to a multipart document
  */
-- (void) addContent: (GSMimeDocument*)newContent
+- (void) addContent: (id)newContent
 {
   if (content == nil)
     {

Source/NSObject.m

@@ -758,31 +758,51 @@ static BOOL double_release_check_enabled = NO;
   return;
 }
 
+/**
+ * Simply calls the +allocWithZone: method passing it
+ * NSDefaultMallocZone() as an argument.
+ */
 + (id) alloc
 {
   return [self allocWithZone: NSDefaultMallocZone()];
 }
 
+/**
+ * Creates a new instance of a class by calling NSAllocateObject()
+ */
 + (id) allocWithZone: (NSZone*)z
 {
   return NSAllocateObject (self, 0, z);
 }
 
+/**
+ * Returns the receiver.
+ */
 + (id) copyWithZone: (NSZone*)z
 {
   return self;
 }
 
+/**
+ * Creates and returns a new instance by calling +alloc and -init
+ */
 + (id) new
 {
   return [[self alloc] init];
 }
 
+/**
+ * Creates and returns a copy of the reciever by calling -copyWithZone:
+ * passing NSDefaultMallocZone()
+ */
 - (id) copy
 {
-  return [(id)self copyWithZone: NULL];
+  return [(id)self copyWithZone: NSDefaultMallocZone()];
 }
 
+/**
+ * Deallocates the receiver by calling NSDeallocateObject()
+ */
 - (void) dealloc
 {
   NSDeallocateObject (self);
@@ -795,26 +815,46 @@ static BOOL double_release_check_enabled = NO;
   return nil;
 }
 
+/**
+ * Initialises the receiver ... the NSObject implementation simply returns self.
+ */
 - (id) init
 {
   return self;
 }
 
+/**
+ * Creates and rturns a mutable copy of the receiver by calling
+ * -mutableCopyWithZone: passing NSDefaultMallocZone().
+ */
 - (id) mutableCopy
 {
-  return [(id)self mutableCopyWithZone: NULL];
+  return [(id)self mutableCopyWithZone: NSDefaultMallocZone()];
 }
 
+/**
+ * Returns the super class from which the recevier was derived.
+ */
 + (Class) superclass
 {
   return class_get_super_class (self);
 }
 
+/**
+ * Returns the super class from which the receviers class was derived.
+ */
 - (Class) superclass
 {
   return object_get_super_class (self);
 }
 
+/**
+ * Returns a flag to say if instances of the receiver class will
+ * respond to the specified selector.  This ignores situations
+ * where a subclass implements -forwardInvocation: to respond to
+ * selectors not normally handled ... in these cases the subclass
+ * may override this method to handle it.
+ */
 + (BOOL) instancesRespondToSelector: (SEL)aSelector
 {
 #if 0
@@ -824,6 +864,9 @@ static BOOL double_release_check_enabled = NO;
 #endif
 }
 
+/**
+ * Returns a flag to say whether the receiving class conforms to aProtocol
+ */
 + (BOOL) conformsToProtocol: (Protocol*)aProtocol
 {
   struct objc_protocol_list* proto_list;
@@ -853,9 +896,13 @@ static BOOL double_release_check_enabled = NO;
     }
 }
 
+/**
+ * Returns a flag to say whether the class of the receiver conforms
+ * to aProtocol.
+ */
 - (BOOL) conformsToProtocol: (Protocol*)aProtocol
 {
-  return [[self class] conformsToProtocol:aProtocol];
+  return [[self class] conformsToProtocol: aProtocol];
 }
 
 + (IMP) instanceMethodForSelector: (SEL)aSelector
@@ -866,6 +913,10 @@ static BOOL double_release_check_enabled = NO;
   return get_imp((Class)self, aSelector);
 }
 
+/**
+ * Returns a pointer to the C function implementing the method used
+ * to respond to messages with aSelector.
+ */
 - (IMP) methodForSelector: (SEL)aSelector
 {
   /*
@@ -877,6 +928,11 @@ static BOOL double_release_check_enabled = NO;
   return get_imp(GSObjCClass(self), aSelector);
 }
 
+/**
+ * Returns a pointer to the C function implementing the method used
+ * to respond to messages with aSelector whihc are sent to instances
+ * of the receiving class.
+ */
 + (NSMethodSignature*) instanceMethodSignatureForSelector: (SEL)aSelector
 {
   struct objc_method* mth = class_get_instance_method(self, aSelector);
@@ -884,6 +940,10 @@ static BOOL double_release_check_enabled = NO;
     : nil;
 }
   
+/**
+ * Returns the method signature describing how the receiver would handle
+ * a message with aSelector.
+ */
 - (NSMethodSignature*) methodSignatureForSelector: (SEL)aSelector
 {
   const char	*types;
@@ -915,17 +975,29 @@ static BOOL double_release_check_enabled = NO;
   return [NSMethodSignature signatureWithObjCTypes: types];
 }
 
+/**
+ * Returns a string describing the receiver.  The default implementation
+ * gives the class and memory location of the rceiver.
+ */
 - (NSString*) description
 {
   return [NSString stringWithFormat: @"<%s: %lx>",
     object_get_class_name(self), (unsigned long)self];
 }
 
+/**
+ * Returns a string describing the receiving class.  The default implementation
+ * gives the name of the class by calling NSStringFromClass().
+ */
 + (NSString*) description
 {
-  return [NSString stringWithCString: object_get_class_name(self)];
+  return NSStringFromClass(self);
 }
 
+/**
+ * Sets up the ObjC runtime so that the receiver is used wherever code
+ * calls for aClassObject to be used.
+ */
 + (void) poseAsClass: (Class)aClassObject
 {
   class_pose_as(self, aClassObject);
@@ -935,31 +1007,45 @@ static BOOL double_release_check_enabled = NO;
    */
 }
 
+/**
+ * Raises an invalid argument exception providing infomration about
+ * the receivers inability to handle aSelector.
+ */
 - (void) doesNotRecognizeSelector: (SEL)aSelector
 {
   [NSException raise: NSInvalidArgumentException
-	       format: @"%s(%s) does not recognize %s",
+	      format: @"%s(%s) does not recognize %s",
 	       object_get_class_name(self), 
 	       GSObjCIsInstance(self) ? "instance" : "class",
 	       sel_get_name(aSelector)];
 }
 
-- (retval_t) forward:(SEL)aSel :(arglist_t)argFrame
+- (retval_t) forward: (SEL)aSel : (arglist_t)argFrame
 {
   NSInvocation *inv;
 
   inv = AUTORELEASE([[NSInvocation alloc] initWithArgframe: argFrame
-				       selector: aSel]);
+						  selector: aSel]);
-  [self forwardInvocation:inv];
+  [self forwardInvocation: inv];
   return [inv returnFrame: argFrame];
 }
 
+/**
+ * This method is called automatically to handle a message sent to
+ * the receiver for which the receivers class has no method.<br />
+ * The default implemnentation calls -doesNotRecognizeSelector:
+ */
 - (void) forwardInvocation: (NSInvocation*)anInvocation
 {
-  [self doesNotRecognizeSelector:[anInvocation selector]];
+  [self doesNotRecognizeSelector: [anInvocation selector]];
   return;
 }
 
+/**
+ * Called after the receiver has been created by decoding some sort
+ * of archive.  Returns self.  Subclasses may override this to perform
+ * some special initialisation upon being decoded.
+ */
 - (id) awakeAfterUsingCoder: (NSCoder*)aDecoder
 {
   return self;
@@ -1024,6 +1110,11 @@ static BOOL double_release_check_enabled = NO;
 
 /* NSObject protocol */
 
+/**
+ * Adds the receiver to the current autorelease pool, so that it will be
+ * sent a -release message when the pool is destroyed.<br />
+ * Returns the receiver.
+ */
 - (id) autorelease
 {
 #if	GS_WITH_GC == 0
@@ -1044,31 +1135,57 @@ static BOOL double_release_check_enabled = NO;
   return self;
 }
 
+/**
+ * Dummy method returning the receiver.
+ */
 + (id) autorelease
 {
   return self;
 }
 
+/**
+ * Returns the receiver.
+ */
 + (Class) class
 {
   return self;
 }
 
+/**
+ * returns the class of which the receiver is an instance.
+ */
 - (Class) class
 {
   return object_get_class(self);
 }
 
+/**
+ * Returns the hash of the receiver.  Subclasses should ensure that their
+ * implementations of this method obey the rule that if the -isEqual: method
+ * returns YES for two instances of the class, the -hash method returns the
+ * same value fro both instances.<br />
+ * The default implementation returns the address of the instance.
+ */
 - (unsigned) hash
 {
   return (unsigned)self;
 }
 
+/**
+ * Tests anObject and the receiver for equality.  The default implementation
+ * considers two objects to be equal only if they are the same object
+ * (ie occupy the same memory location).<br />
+ * If a subclass overrides this method, it should also override the -hash
+ * method so that if two objects are equal they both have the same hash.
+ */
 - (BOOL) isEqual: (id)anObject
 {
   return (self == anObject);
 }
 
+/**
+ * Returns YES if aClass is the NSObject class
+ */
 + (BOOL) isKindOfClass: (Class)aClass
 {
   if (aClass == [NSObject class])
@@ -1076,6 +1193,10 @@ static BOOL double_release_check_enabled = NO;
   return NO;
 }
 
+/**
+ * Returns YES if the class of the receiver is either the same as aClass
+ * or is derived from (a subclass of) aClass.
+ */
 - (BOOL) isKindOfClass: (Class)aClass
 {
   Class class = GSObjCClass(self);
@@ -1083,21 +1204,38 @@ static BOOL double_release_check_enabled = NO;
   return GSObjCIsKindOf(class, aClass);
 }
 
+/**
+ * Returns YES if aClass is the same as the receiving class.
+ */
 + (BOOL) isMemberOfClass: (Class)aClass
 {
   return (self == aClass) ? YES : NO;
 }
 
+/**
+ * Returns YES if the class of the receiver is aClass
+ */
 - (BOOL) isMemberOfClass: (Class)aClass
 {
   return (GSObjCClass(self) == aClass) ? YES : NO;
 }
 
+/**
+ * Returns a flag to differnetiate between 'true' objects, and objects
+ * which are proxies for other objects (ie they forward messages to the
+ * other objects).<br />
+ * The default implementation returns NO.
+ */
 - (BOOL) isProxy
 {
   return NO;
 }
 
+/**
+ * Causes the receiver to execute the method implementation corresponding
+ * to aSelector and returns the result.<br />
+ * The method must be one which takes no arguments and returns an object.
+ */
 - (id) performSelector: (SEL)aSelector
 {
   IMP msg;
@@ -1119,6 +1257,11 @@ static BOOL double_release_check_enabled = NO;
   return (*msg)(self, aSelector);
 }
 
+/**
+ * Causes the receiver to execute the method implementation corresponding
+ * to aSelector and returns the result.<br />
+ * The method must be one which takes one argument and returns an object.
+ */
 - (id) performSelector: (SEL)aSelector withObject: (id) anObject
 {
   IMP msg;
@@ -1141,6 +1284,11 @@ static BOOL double_release_check_enabled = NO;
   return (*msg)(self, aSelector, anObject);
 }
 
+/**
+ * Causes the receiver to execute the method implementation corresponding
+ * to aSelector and returns the result.<br />
+ * The method must be one which takes two arguments and returns an object.
+ */
 - (id) performSelector: (SEL)aSelector
 	    withObject: (id) object1
 	    withObject: (id) object2
@@ -1204,6 +1352,13 @@ static BOOL double_release_check_enabled = NO;
   return;
 }
 
+/**
+ * Returns a flag to say if the receiver will
+ * respond to the specified selector.  This ignores situations
+ * where a subclass implements -forwardInvocation: to respond to
+ * selectors not normally handled ... in these cases the subclass
+ * may override this method to handle it.
+ */
 - (BOOL) respondsToSelector: (SEL)aSelector
 {
   return __objc_responds_to(self, aSelector);
@@ -1256,31 +1411,53 @@ static BOOL double_release_check_enabled = NO;
   return UINT_MAX;
 }
 
+/**
+ * Returns the reciever.
+ */
 - (id) self
 {
   return self;
 }
 
+/**
+ * Returns the memory allocation zone in which the receiver is located.
+ */
 - (NSZone*) zone
 {
   return GSObjCZone(self);
 }
 
+/**
+ * Called to encode the instance variables of the receiver to aCoder.<br />
+ * Subclasses should call the superclass method at the start of their
+ * own implementation.
+ */
 - (void) encodeWithCoder: (NSCoder*)aCoder
 {
   return;
 }
 
+/**
+ * Called to intialise instance variables of the receiver from aDecoder.<br />
+ * Subclasses should call the superclass method at the start of their
+ * own implementation.
+ */
 - (id) initWithCoder: (NSCoder*)aDecoder
 {
   return self;
 }
 
+/**
+ * Returns the version number of the receiving class.
+ */
 + (int) version
 {
   return class_get_version(self);
 }
 
+/**
+ * Sets the version number of the receiving class.
+ */
 + (id) setVersion: (int)aVersion
 {
   if (aVersion < 0)
@@ -1298,7 +1475,7 @@ static BOOL double_release_check_enabled = NO;
 
 /* NEXTSTEP Object class compatibility */
 
-- error: (const char *)aString, ...
+- (id) error: (const char *)aString, ...
 {
 #define FMT "error: %s (%s)\n%s\n"
   char fmt[(strlen((char*)FMT)+strlen((char*)object_get_class_name(self))
@@ -1316,10 +1493,12 @@ static BOOL double_release_check_enabled = NO;
 #undef FMT
 }
 
+/*
 - (const char *) name
 {
   return object_get_class_name(self);
 }
+*/
 
 - (BOOL) isKindOf: (Class)aClassObject
 {
@@ -1419,22 +1598,39 @@ static BOOL double_release_check_enabled = NO;
 
 /* GNU Object class compatibility */
 
+/**
+ * Called to change the class used for autoreleasing objects.
+ */
 + (void) setAutoreleaseClass: (Class)aClass
 {
   autorelease_class = aClass;
   autorelease_imp = [self instanceMethodForSelector: autorelease_sel];
 }
 
+/**
+ * returns the class used to autorelease objects.
+ */
 + (Class) autoreleaseClass
 {
   return autorelease_class;
 }
 
+/**
+ * Enables runtime checking of retain/release/autorelease operations.<br />
+ * Whenever either -autorelease or -release is called, the contents of any
+ * autorelease pools will be checked to see if there are more outstanding
+ * release operations than the objects retain count.  In which case an
+ * exception is raised to say that the object is released too many times.
+ */
 + (void) enableDoubleReleaseCheck: (BOOL)enable
 {
   double_release_check_enabled = enable;
 }
 
+/**
+ * Compare the receiver with anObject to see which is greater.
+ * The default implementation orders by memory location.
+ */
 - (int) compare: (id)anObject
 {
   if (anObject == self)
@@ -1502,11 +1698,21 @@ static BOOL double_release_check_enabled = NO;
     [(id)self descriptionWithLocale: aLocale indent: level]];
 }
 
+/**
+ * Returns a flag to say whether dealloc notifications should be done.<br />
+ * See the -setDeallocNotificationsActive: method.
+ */
 - (BOOL) deallocNotificationsActive
 {
   return deallocNotifications;
 }
 
+/**
+ * Sets a flag to indicate whether dealloc notifications should be done.<br />
+ * If this flag is set, when an object is to be deallocated the -_dealloc
+ * method will be called first to notify the object that it is about to be
+ * deallocated.
+ */
 - (void) setDeallocNotificationsActive: (BOOL)flag
 {
   deallocNotifications = flag;