added GSdoc comments to class, method, and function declarations; for some classes some comments were already in the source file (not the header), in which case further comments were added here; otherwise comments were put in the headers

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

Headers/Foundation/NSArchiver.h

@@ -21,10 +21,9 @@
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
 
-   AutogsdocSource: NSArchiver.m
+   AutogsdocSource:NSUnarchiver.m
-   AutogsdocSource: NSUnarchiver.m
+   AutogsdocSource:NSArchiver.m
-
+*/ 
-   */ 
 
 #ifndef __NSArchiver_h_GNUSTEP_BASE_INCLUDE
 #define __NSArchiver_h_GNUSTEP_BASE_INCLUDE

Headers/Foundation/NSAutoreleasePool.h

@@ -79,8 +79,9 @@ typedef struct autorelease_array_list
  *   object gets deallocated.
  * </p>
  * <p>
- *   A simple retain/release mechanism is not very interesting ...
+ *   A simple retain/release mechanism has problems with passing objects
- *   so it's spiced up with autorelease pools.  You can use the
+ *   from one scope to another,
+ *   so it's augmented with autorelease pools.  You can use the
  *   AUTORELEASE() macro to call the [NSObject-autorelease]
  *   method, which adds an object to the current autorelease pool by
  *   calling [NSAutoreleasePool+addObject:].<br />
@@ -127,7 +128,7 @@ typedef struct autorelease_array_list
  *   <desc>
  *     Methods whose names begin with init return an initialised
  *     version of the receiving object, owned by the caller.<br />
- *     NB. The returned object may not actualy be the same as the
+ *     NB. The returned object may not actually be the same as the
  *     receiver ... sometimes an init method releases the original
  *     receiver and returns an alternative.
  *   </desc>

Headers/Foundation/NSBitmapCharSet.h

@@ -27,6 +27,7 @@
 #include <Foundation/NSCharacterSet.h>
 #include <Foundation/NSData.h>
 
+//PENDING: may want to make these less likely to conflict
 #define UNICODE_SIZE	65536
 #define BITMAP_SIZE	UNICODE_SIZE/8
 
@@ -36,20 +37,35 @@
 #define ISSET(a,i)      ((((a) & (1<<(i)))) > 0) ? YES : NO;
 #endif
 
+/**
+ *  An [NSCharacterSet] that stores the set of unicode characters in it as a
+ *  simple bitmap.  Implementation is very efficient.
+ */
 @interface NSBitmapCharSet : NSCharacterSet
 {
   char _data[BITMAP_SIZE];
 }
 
+/**
+ *  Init directly with bitmap data.  bitmap should be <code>BITMAP_SIZE</code>
+ *  long, which is currently 2^16 / 8.
+ */
 - (id) initWithBitmap: (NSData*)bitmap;
 
 @end
 
+/**
+ *  Mutable version of [NSBitmapCharSet].
+ */
 @interface NSMutableBitmapCharSet : NSMutableCharacterSet
 {
   char _data[BITMAP_SIZE];
 }
 
+/**
+ *  Init directly with bitmap data.  bitmap should be <code>BITMAP_SIZE</code>
+ *  long, which is currently 2^16 / 8.
+ */
 - (id) initWithBitmap: (NSData*)bitmap;
 
 @end

Headers/Foundation/NSBundle.h

@@ -140,7 +140,7 @@ GS_EXPORT NSString* NSLoadedClasses;
 		  inDirectory: (NSString*)bundlePath;
 
 /**
-  This method has been depreciated. Version numbers were never implemented
+  This method has been deprecated. Version numbers were never implemented
   so this method behaves exactly like +pathForResource:ofType:inDirectory:.
  */
 + (NSString*) pathForResource: (NSString*)name
@@ -173,6 +173,10 @@ GS_EXPORT NSString* NSLoadedClasses;
  */
 - (Class) principalClass;
 
+/**
+ *  Not implemented.  Create an instance and call the corresponding instance
+ *  method instead.
+ */
 + (NSArray*) pathsForResourcesOfType: (NSString*)extension
 			 inDirectory: (NSString*)bundlePath;
 
@@ -241,14 +245,29 @@ GS_EXPORT NSString* NSLoadedClasses;
 - (void) setBundleVersion: (unsigned)version;
 
 #ifndef STRICT_OPENSTEP
+/**
+ *  Returns subarray of given array containing those localizations that are
+ *  used to locate resources given environment and user preferences.
+ */
 + (NSArray *) preferredLocalizationsFromArray: (NSArray *)localizationsArray;
+/**
+ *  Returns subarray of given array containing those localizations that are
+ *  used to locate resources given environment given user preferences (which
+ *  are used instead of looking up the preferences of the current user).
+ */
 + (NSArray *) preferredLocalizationsFromArray: (NSArray *)localizationsArray 
 			       forPreferences: (NSArray *)preferencesArray;
 
 - (BOOL) isLoaded;
+/**
+ *  Not implemented.
+ */
 - (NSArray*) pathsForResourcesOfType: (NSString*)extension
 			 inDirectory: (NSString*)bundlePath
 		     forLocalization: (NSString*)localizationName;
+/**
+ *  Not implemented.
+ */
 - (NSString*) pathForResource: (NSString*)name
 		       ofType: (NSString*)ext
 		  inDirectory: (NSString*)bundlePath
@@ -285,6 +304,10 @@ GS_EXPORT NSString* NSLoadedClasses;
 @end
 
 #ifndef	 NO_GNUSTEP
+/**
+ *  Augments [NSBundle], including methods for handling libraries in the GNUstep
+ *  fashion, for rapid localization, and other purposes.
+ */
 @interface NSBundle (GNUstep)
 
 /** This method is an experimental GNUstep extension, and
@@ -301,15 +324,15 @@ GS_EXPORT NSString* NSLoadedClasses;
 + (NSString*) _gnustep_target_os;
 + (NSString*) _library_combo;
 
-/** Find a resource in the "Library" directory */
+/** Find a resource in the "Library" directory. */
 + (NSString*) pathForLibraryResource: (NSString*)name
 			      ofType: (NSString*)ext
 			 inDirectory: (NSString*)bundlePath;
 
-/** Depreciated. Use +bundleForLibrary: instead. */
+/** Deprecated. Use +bundleForLibrary: instead. */
 + (NSBundle*) gnustepBundle;
 
-/** Depreciated. Use +pathForLibraryResource:ofType:inDirectory: 
+/** Deprecated. Use +pathForLibraryResource:ofType:inDirectory: 
     or +bundleForLibrary: instead. */
 + (NSString*) pathForGNUstepResource: (NSString*)name
 			      ofType: (NSString*)ext

Headers/Foundation/NSCalendarDate.h

@@ -106,7 +106,20 @@
 
 #ifndef	NO_GNUSTEP
 
+/**
+ *  Adds <code>-weekOfYear</code> method.
+ */
 @interface NSCalendarDate (GSCategories)
+/**
+ * The ISO standard week of the year is based on the first week of the
+ * year being that week (starting on monday) for which the thursday
+ * is on or after the first of january.<br />
+ * This has the effect that, if january first is a friday, saturday or
+ * sunday, the days of that week (up to and including the sunday) are
+ * considered to be in week 53 of the preceeding year. Similarly if the
+ * last day of the year is a monday tuesday or wednesday, these days are
+ * part of week 1 of the next year.
+ */
 - (int) weekOfYear;
 @end
 

Headers/Foundation/NSCoder.h

@@ -30,51 +30,191 @@
 
 @class NSMutableData, NSData, NSString;
 
+/**
+ *  <p>Top-level class defining methods for use when archiving (encoding)
+ *  objects to a byte array or file, and when restoring (decoding) objects.
+ *  Generally only subclasses of this class are used directly - [NSArchiver],
+ *  [NSUnarchiver], [NSKeyedArchiver], [NSKeyedUnarchiver], or [NSPortCoder].
+ *  </p>
+ *  <p><code>NSPortCoder</code> is used within the distributed objects
+ *  framework.  For archiving to/from disk, the <em>Keyed...</em> classes are
+ *  preferred for new implementations, since they provide greater
+ *  forward/backward compatibility in the face of class changes.</p>
+ */
 @interface NSCoder : NSObject
 // Encoding Data
 
+/**
+ *  Encodes array of count structures or objects of given type, which may be
+ *  obtained through the '<code>@encode(...)</code>' compile-time operator.
+ *  Usually this is used for primitives though it can be used for objects as
+ *  well.
+ */
 - (void) encodeArrayOfObjCType: (const char*)type
 			 count: (unsigned)count
 			    at: (const void*)array;
+
+/**
+ *  Can be ignored.
+ */
 - (void) encodeBycopyObject: (id)anObject;
+/**
+ *  Can be ignored.
+ */
 - (void) encodeByrefObject: (id)anObject;
+
+/**
+ *  Stores bytes directly into archive.  
+ */
 - (void) encodeBytes: (void*)d length: (unsigned)l;
+
+/**
+ *  Encode object if it is/will be encoded unconditionally by this coder,
+ *  otherwise store a nil.
+ */
 - (void) encodeConditionalObject: (id)anObject;
+
+/**
+ *  Encode an instance of [NSData].
+ */
 - (void) encodeDataObject: (NSData*)data;
+
+/**
+ *  Encodes a generic object.  This will usually result in an [NSCoding
+ *  -encodeWithCoder:] message being sent to anObject so it can encode itself.
+ */
 - (void) encodeObject: (id)anObject;
+
+/**
+ *  Encodes a property list by calling [NSSerializer -serializePropertyList:],
+ *  then encoding the resulting [NSData] object.
+ */
 - (void) encodePropertyList: (id)plist;
+
+/**
+ *  Encodes a point structure.
+ */
 - (void) encodePoint: (NSPoint)point;
+
+/**
+ *  Encodes a rectangle structure.
+ */
 - (void) encodeRect: (NSRect)rect;
+
+/**
+ *  Store object and objects it refers to in archive (i.e., complete object
+ *  graph).
+ */
 - (void) encodeRootObject: (id)rootObject;
+
+/**
+ *  Encodes a size structure.
+ */
 - (void) encodeSize: (NSSize)size;
+
+/**
+ *  Encodes structure or object of given type, which may be obtained
+ *  through the '<code>@encode(...)</code>' compile-time operator.  Usually
+ *  this is used for primitives though it can be used for objects as well.
+ */
 - (void) encodeValueOfObjCType: (const char*)type
 			    at: (const void*)address;
+
+/**
+ *  Multiple version of [-encodeValueOfObjCType:at:].
+ */
 - (void) encodeValuesOfObjCTypes: (const char*)types,...;
 
 // Decoding Data
 
+/**
+ *  Decodes array of count structures or objects of given type, which may be
+ *  obtained through the '<code>@encode(...)</code>' compile-time operator.
+ *  Usually this is used for primitives though it can be used for objects as
+ *  well.  Objects will be retained and you must release them.
+ */
 - (void) decodeArrayOfObjCType: (const char*)type
                          count: (unsigned)count
                             at: (void*)address;
+
+/**
+ *  Retrieve bytes directly from archive.
+ */
 - (void*) decodeBytesWithReturnedLength: (unsigned*)l;
+
+/**
+ *  Decode an instance of [NSData].
+ */
 - (NSData*) decodeDataObject;
+
+/**
+ *  Decodes a generic object.  Usually the class will be read from the
+ *  archive, an object will be created through an <code>alloc</code> call,
+ *  then that class will be sent an [NSCoding -initWithCoder:] message.
+ */
 - (id) decodeObject;
+
+/**
+ *  Decodes a property list from the archive previously stored through a call
+ *  to [-encodePropertyList:].
+ */
 - (id) decodePropertyList;
+
+/**
+ *  Decodes a point structure.
+ */
 - (NSPoint) decodePoint;
+
+/**
+ *  Decodes a rectangle structure.
+ */
 - (NSRect) decodeRect;
+
+/**
+ *  Decodes a size structure.
+ */
 - (NSSize) decodeSize;
+
+/**
+ *  Decodes structure or object of given type, which may be obtained
+ *  through the '<code>@encode(...)</code>' compile-time operator.  Usually
+ *  this is used for primitives though it can be used for objects as well,
+ *  in which case you are responsible for releasing them.
+ */
 - (void) decodeValueOfObjCType: (const char*)type
 			    at: (void*)address;
+
+/**
+ *  Multiple version of [-decodeValueOfObjCType:at:].
+ */
 - (void) decodeValuesOfObjCTypes: (const char*)types,...;
 
 // Managing Zones
 
+/**
+ *  Returns zone being used to allocate memory for decoded objects.
+ */
 - (NSZone*) objectZone;
+
+/**
+ *  Sets zone to use for allocating memory for decoded objects.
+ */
 - (void) setObjectZone: (NSZone*)zone;
 
 // Getting a Version
 
+/**
+ *  Returns *Step version, which is not the release version, but a large number,
+ *  by specification &lt;1000 for pre-OpenStep.  This implementation returns
+ *  a number based on the GNUstep major, minor, and subminor versions.
+ */
 - (unsigned int) systemVersion;
+
+/**
+ *  Returns current version of class (when encoding) or version of decoded
+ *  class (decoded).  Version comes from [NSObject -getVersion].
+ *  
+ */
 - (unsigned int) versionForClassName: (NSString*)className;
 
 #ifndef	STRICT_OPENSTEP
@@ -162,7 +302,7 @@
 - (void) encodeBool: (BOOL) aBool forKey: (NSString*)aKey;
 
 /** <override-subclass />
- * Encodes the data of the specified length and pointed to by aPointeraBool,
+ * Encodes the data of the specified length and pointed to by aPointer,
  * and associates the encoded value with aKey.
  */
 - (void) encodeBytes: (const uint8_t*)aPointer
@@ -209,6 +349,9 @@
 
 #ifndef NO_GNUSTEP
 
+/**
+ *  GNUstep extensions to [NSCoder], supporting compatibility with libObjects.
+ */
 @interface NSCoder (GNUstep)
 /* Compatibility with libObjects */
 - (void) decodeArrayOfObjCType: (const char*)type

Headers/Foundation/NSConnection.h

@@ -146,22 +146,41 @@ GS_EXPORT NSString *NSConnectionProxyCount;	/* Objects received	*/
 @end
 
 
-/*
+/**
- *	This catagory contains legacy methods from the original GNU 'Connection'
+ *	This category contains legacy methods from the original GNU 'Connection'
- *	class, and useful extensions to NSConnection.
+ *	class, and useful extensions to [NSConnection].
  */
 @interface NSConnection (GNUstepExtensions) <GCFinalization>
 
+/**
+ *  Alternative convenience constructor, not specified in OpenStep, where you
+ *  registe root anObject under given name in one step.
+ */
 + (NSConnection*) newRegisteringAtName: (NSString*)name
 			withRootObject: (id)anObject;
 
+/**
+ * Performs local and remote cleanup.
+ */
 - (void) gcFinalize;
 
+/**
+ * [NSDistantObject -forward::] calls this to send the message over the wire.
+ */
 - (retval_t) forwardForProxy: (NSDistantObject*)object 
 		    selector: (SEL)sel 
 		    argFrame: (arglist_t)argframe;
+
+/**
+ * [NSDistantObject -forwardInvocation:] calls this to send the message over
+ * the wire.
+ */
 - (void) forwardInvocation: (NSInvocation *)inv 
 		  forProxy: (NSDistantObject*)object;
+
+/**
+ *  Returns type code (@encode()-compatible) for given remote method.
+ */
 - (const char *) typeForSelector: (SEL)sel remoteTarget: (unsigned)target;
 
 @end
@@ -169,8 +188,8 @@ GS_EXPORT NSString *NSConnectionProxyCount;	/* Objects received	*/
 GS_EXPORT NSString *ConnectionBecameInvalidNotification;
 
 @interface Object (NSConnectionDelegate)
-/*
+/**
- *	This method may be used to ask a delegates permission to create
+ *	This method may be used to ask a delegate's permission to create
  *	a new connection from the old one.
  *	This method should be implemented in preference to the
  *	[makeNewConnection:sender:] which is obsolete.
@@ -178,7 +197,7 @@ GS_EXPORT NSString *ConnectionBecameInvalidNotification;
 - (BOOL) connection: (NSConnection*)parent
   shouldMakeNewConnection: (NSConnection*)newConnection;
 
-/*
+/**
  *	This is the old way of doing the same thing as
  *	[connection:shouldMakeNewConnection:]
  *	It is obsolete - don't use it.
@@ -186,7 +205,7 @@ GS_EXPORT NSString *ConnectionBecameInvalidNotification;
 - (BOOL) makeNewConnection: (NSConnection*)newConnection
 		    sender: (NSConnection*)parent;
 
-/*
+/**
  *	If the delegate responds to this method, it will be used to ask the
  *	delegate's permission to establish a new connection from the old one.
  *	Often this is used so that the delegate can register for invalidation 
@@ -197,20 +216,29 @@ GS_EXPORT NSString *ConnectionBecameInvalidNotification;
 - (NSConnection*) connection: (NSConnection*)ancestorConn
 		  didConnect: (NSConnection*)newConn;
 
-/*
+/**
  * These are like the MacOS-X delegate methods, except that we provide the
  * components in mutable arrays, so that the delegate can alter the data
  * items in the array.  Of course, you must do that WITH CARE.
  */ 
 - (BOOL) authenticateComponents: (NSMutableArray*)components
 		       withData: (NSData*)authenticationData;
+
+/**
+ * These are like the MacOS-X delegate methods, except that we provide the
+ * components in mutable arrays, so that the delegate can alter the data
+ * items in the array.  Of course, you must do that WITH CARE.
+ */ 
 - (NSData*) authenticationDataForComponents: (NSMutableArray*)components;
 
 @end
 
+/**
+ * This informal protocol allows an object to control the details of how an
+ * object is sent over the wire in distributed objects Port communications.
+ */
 @interface Object (NSPortCoder)
-- (Class) classForPortCoder;
+/**
-/*
  *	Must return the class that will be created on the remote side
  *	of the connection.  If the class to be created is not the same
  *	as that of the object returned by replacementObjectForPortCoder:
@@ -221,14 +249,16 @@ GS_EXPORT NSString *ConnectionBecameInvalidNotification;
  *	class is returned.  To force bycopy operation the object should
  *	return its own class.
  */
-- (id) replacementObjectForPortCoder: (NSPortCoder*)aCoder;
+- (Class) classForPortCoder;
-/*
+
+/**
  *	This message is sent to an object about to be encoded for sending
  *	over the wire.  The default action is to return an NSDistantObject
  *	which is a local proxy for the object unless the object is being
  *	sent bycopy, in which case the actual object is returned.
- *	To force bycopy, an object should return itsself.
+ *	To force bycopy, an object should return itself.
  */
+- (id) replacementObjectForPortCoder: (NSPortCoder*)aCoder;
 
 @end
 

Headers/Foundation/NSData.h

@@ -116,13 +116,70 @@
 
 #ifndef NO_GNUSTEP
 
+/**
+ * Extension methods for the NSData class- mainly conversion utilities.
+ */
 @interface NSData (GSCategories)
+
+/**
+ * Returns an NSString object containing an ASCII hexadecimal representation
+ * of the receiver.  This means that the returned object will contain
+ * exactly twice as many characters as there are bytes as the receiver,
+ * as each byte in the receiver is represented by two hexadecimal digits.<br />
+ * The high order four bits of each byte is encoded before the low
+ * order four bits.  Capital letters 'A' to 'F' are used to represent
+ * values from 10 to 15.<br />
+ * If you need the hexadecimal representation as raw byte data, use code
+ * like -
+ * <example>
+ *   hexData = [[sourceData hexadecimalRepresentation]
+ *     dataUsingEncoding: NSASCIIStringEncoding];
+ * </example>
+ */
 - (NSString*) hexadecimalRepresentation;
+
+/**
+ * Initialises the receiver with the supplied string data which contains
+ * a hexadecimal coding of the bytes.  The parsing of the string is
+ * fairly tolerant, ignoring whitespace and permitting both upper and
+ * lower case hexadecimal digits (the -hexadecimalRepresentation method
+ * produces a string using only uppercase digits with no white spaqce).<br />
+ * If the string does not contain one or more pairs of hexadecimal digits
+ * then an exception is raised. 
+ */
 - (id) initWithHexadecimalRepresentation: (NSString*)string;
+
+/**
+ * Creates an MD5 digest of the information stored in the receiver and
+ * returns it as an autoreleased 16 byte NSData object.<br />
+ * If you need to produce a digest of string information, you need to
+ * decide what character encoding is to be used and convert your string
+ * to a data object of that encoding type first using the
+ * [NSString-dataUsingEncoding:] method -
+ * <example>
+ *   myDigest = [[myString dataUsingEncoding: NSUTF8StringEncoding] md5Digest];
+ * </example>
+ * If you need to use the digest in a human readable form, you will
+ * probably want it to be seen as 32 hexadecimal digits, and can do that
+ * using the -hexadecimalRepresentation method.
+ */
 - (NSData*) md5Digest;
+
+/**
+ * Decodes the source data from uuencoded and return the result.<br />
+ * Returns the encoded file name in namePtr if it is not null.
+ * Returns the encoded file mode in modePtr if it is not null.
+ */
 - (BOOL) uudecodeInto: (NSMutableData*)decoded
 		 name: (NSString**)namePtr
 		 mode: (int*)modePtr;
+
+/**
+ * Encode the source data to uuencoded.<br />
+ * Uses the supplied name as the filename in the encoded data,
+ * and says that the file mode is as specified.<br />
+ * If no name is supplied, uses <code>untitled</code> as the name.
+ */
 - (BOOL) uuencodeInto: (NSMutableData*)encoded
 		 name: (NSString*)name
 		 mode: (int)mode;

Headers/Foundation/NSDateFormatter.h

@@ -29,6 +29,67 @@
 
 #include <Foundation/NSFormatter.h>
 
+/**
+ *  <p>Class for generating text representations of [NSDate]s and
+ *  [NSCalendarDate]s, and for converting strings into instances of these
+ *  objects.  Note that [NSDate] and [NSCalendarDate] do contain some
+ *  string conversion methods, but using this class provides more control
+ *  over conversion.</p>
+ *  <p>See the [NSFormatter] documentation for description of the basic methods
+ *  for formatting and parsing that are available.</p>
+ *  <p>The basic format of a format string uses "%" codes to represent
+ *  components of the date.  Thus, for example, <code>@"%b %d, %Y"</code>
+ *  specifies strings similar to "June 18, 1991".  The full list of codes is
+ *  as follows:</p>
+ *  <deflist>
+ *  <term>%%</term>
+ *  <desc>a '%' character</desc>
+ *  <term>%a</term>
+ *  <desc>abbreviated weekday name</desc>
+ *  <term>%A</term>
+ *  <desc>full weekday name</desc>
+ *  <term>%b</term>
+ *  <desc>abbreviated month name</desc>
+ *  <term>%B</term>
+ *  <desc>full month name</desc>
+ *  <term>%c</term>
+ *  <desc>shorthand for "%X %x", the locale format for date and time</desc>
+ *  <term>%d</term>
+ *  <desc>day of the month as a decimal number (01-31)</desc>
+ *  <term>%e</term>
+ *  <desc>same as %d but does not print the leading 0 for days 1 through 9 (unlike strftime(), does not print a leading space)</desc>
+ *  <term>%F</term>
+ *  <desc>milliseconds as a decimal number (000-999)</desc>
+ *  <term>%H</term>
+ *  <desc>hour based on a 24-hour clock as a decimal number (00-23)</desc>
+ *  <term>%I</term>
+ *  <desc>hour based on a 12-hour clock as a decimal number (01-12)</desc>
+ *  <term>%j</term>
+ *  <desc>day of the year as a decimal number (001-366)</desc>
+ *  <term>%m</term>
+ *  <desc>month as a decimal number (01-12)</desc>
+ *  <term>%M</term>
+ *  <desc>minute as a decimal number (00-59)</desc>
+ *  <term>%p</term>
+ *  <desc>AM/PM designation for the locale</desc>
+ *  <term>%S</term>
+ *  <desc>second as a decimal number (00-59)</desc>
+ *  <term>%w</term>
+ *  <desc>weekday as a decimal number (0-6), where Sunday is 0</desc>
+ *  <term>%x</term>
+ *  <desc>date using the date representation for the locale, including the time zone (produces different results from strftime())</desc>
+ *  <term>%X</term>
+ *  <desc>time using the time representation for the locale (produces different results from strftime())</desc>
+ *  <term>%y</term>
+ *  <desc>year without century (00-99)</desc>
+ *  <term>%Y</term>
+ *  <desc>year with century (such as 1990)</desc>
+ *  <term>%Z</term>
+ *  <desc>time zone name (such as Pacific Daylight Time; produces different results from strftime())</desc>
+ *  <term>%z</term>
+ *  <desc>time zone offset in hours and minutes from GMT (HHMM)</desc>
+ * </deflist>
+ */
 @interface NSDateFormatter : NSFormatter <NSCoding, NSCopying>
 {
   NSString	*_dateFormat;
@@ -36,11 +97,34 @@
 }
 
 /* Initializing an NSDateFormatter */
+
+/**
+ *  Initialize with given specifier string format.  See class description for
+ *  how to specify a format string.  If flag is YES, string-to-object
+ *  conversion will attempt to process strings as natural language dates, such
+ *  as "yesterday", or "first Tuesday of next month" if straight format-based
+ *  conversion fails.
+ */
 - (id) initWithDateFormat: (NSString *)format
      allowNaturalLanguage: (BOOL)flag;
 
+
 /* Determining Attributes */
+
+/**
+ *  Returns whether initialized to support natural language formatting.  If
+ *  YES, string-to-object conversion will attempt to process strings as
+ *  natural language dates, such as "yesterday", or "first Tuesday of next
+ *  month" if straight format-based conversion fails.
+ */
 - (BOOL) allowsNaturalLanguage;
+
+/**
+ *  Returns format string initialized with, specifying how dates are formatted,
+ *  for object-to-string conversion, and how they are parsed, for
+ *  string-to-object conversion.  For example, <code>@"%b %d, %Y"</code>
+ *  specifies strings similar to "June 18, 1991".
+ */
 - (NSString *) dateFormat;
 @end
 

Headers/Foundation/NSDebug.h

@@ -220,8 +220,9 @@ GS_EXPORT BOOL NSDeallocateZombies;
    </p>
    <p>NSProcess initialises a set of strings that are the names of active
    debug levels using the '--GNU-Debug=...' command line argument.
-   Each command-line argument of that form is removed from NSProcessInfos
+   Each command-line argument of that form is removed from
-   list of arguments and the variable part (...) is added to the set.
+   <code>NSProcessInfo</code>'s list of arguments and the variable part
+   (...) is added to the set.
    This means that as far as the program proper is concerned, it is
    running with the same arguments as if debugging had not been enabled.
    </p>
@@ -233,7 +234,7 @@ GS_EXPORT BOOL NSDeallocateZombies;
    <p>NSUserDefaults also adds debug levels from the array given by the
    GNU-Debug key ... but these values will not take effect until the
    +standardUserDefaults method is called ... so they are useless for
-   debugging NSUserDefaults itsself or for debugging any code executed
+   debugging NSUserDefaults itself or for debugging any code executed
    before the defaults system is used.
    </p>
    <p>To embed debug logging in your code you use the NSDebugLLog() or
@@ -395,7 +396,7 @@ GS_EXPORT BOOL NSDeallocateZombies;
    something that it not necessarily fatal or illegal, but looks like it
    might be a programming error.  eg. attempting to remove 'nil' from an
    NSArray, which the Spec/documentation does not prohibit, but which a
-   well written progam should not be attempting (since an NSArray object
+   well written program should not be attempting (since an NSArray object
    cannot contain a 'nil').
    </p>
    <p>NB. The 'warn=yes' option is understood by the GNUstep make package
@@ -405,7 +406,7 @@ GS_EXPORT BOOL NSDeallocateZombies;
    <p>To embed debug logging in your code you use the NSWarnLog() macro.
    </p>
    <p>As a convenience, there are two more logging macros you can use -
-   NSWarnLog(), and NSWarnMLog().
+   NSWarnFLog(), and NSWarnMLog().
    These are specifically for use in either functions or methods and
    prepend information about the file, line and either function or
    class/method in which the message was generated.

Headers/Foundation/NSDecimal.h

@@ -50,7 +50,7 @@ typedef enum {
   NSCalculationDivideByZero
 } NSCalculationError;
 
-/*
+/**
  *	Give a precision of at least 38 decimal digits
  *	requires 128 bits.
  */
@@ -59,6 +59,21 @@ typedef enum {
 #define NSDecimalMaxDigit 38
 #define NSDecimalNoScale 128
 
+/**
+ *  <p>Structure providing equivalent functionality, in conjunction with a set
+ *  of functions, to the [NSDecimalNumber] class.</p>
+<example>
+typedef struct {
+  signed char	exponent;   // Signed exponent - -128 to 127
+  BOOL	isNegative;         // Is this negative?
+  BOOL	validNumber;        // Is this a valid number?
+  unsigned char	length;	    // digits in mantissa.
+  unsigned char  cMantissa[2*NSDecimalMaxDigit];
+} NSDecimal;
+</example>
+* <p>Instances can be initialized using the NSDecimalFromString(NSString *)
+* function.</p>
+ */
 typedef struct {
   signed char	exponent;	/* Signed exponent - -128 to 127	*/
   BOOL	isNegative;	/* Is this negative?			*/

Headers/Foundation/NSDecimalNumber.h

@@ -33,15 +33,87 @@
 
 @class	NSDecimalNumber;
 
+/**
+ *  This protocol encapsulates information about how an [NSDecimalNumber]
+ *  should round and process exceptions.  Usually you can just create objects
+ *  of the [NSDecimalNumberHandler] class, which implements this protocol, but
+ *  if you don't want to use that class you can create your own implementing
+ *  it.
+ */
 @protocol	NSDecimalNumberBehaviors
+
+/**
+ *  <p>Specifies behavior when, in the course of applying method to leftOperand
+ *  and rightOperand, an [NSDecimalNumber] instance encounters given error.</p>
+ *  <p>error has four possible constant values:</p>
+ *  <deflist>
+ *  <term><code>NSCalculationLossOfPrecision</code></term>
+ *  <desc>The number can't be represented in 38 significant digits.</desc>
+ *  <term><code>NSCalculationOverflow</code></term>
+ *  <desc>The number is too large to represent.</desc>
+ *  <term><code>NSCalculationUnderflow</code></term>
+ *  <desc>The number is too small to represent.</desc>
+ *  <term><code>NSCalculationDivideByZero</code></term>
+ *  <desc>The caller tried to divide by 0.</desc>
+ *  </deflist>
+ *
+ *  <p>Behavior on error can be one of the following:</p>
+ *  <list>
+ *  <item>Raise an exception.</item>
+ *  <item>Return nil.  The calling method will return its value as though no
+ *    error had occurred. If error is
+ *    <code>NSCalculationLossOfPrecision</code>, method will return an
+ *    imprecise value, constrained to 38 significant digits.  If error is
+ *    <code>NSCalculationUnderflow</code> or
+ *    <code>NSCalculationOverflow</code>, method will return
+ *    <code>NSDecimalNumber</code>'s <code>notANumber</code>. You shouldn't
+ *    return nil if error is <code>NSDivideByZero</code>.
+ *  </item>
+ *  <item>Correct the error and return a valid <code>NSDecimalNumber</code>.
+ *    The calling method will use this as its own return value.</item>
+ *  </list>
+ */
 - (NSDecimalNumber*) exceptionDuringOperation: (SEL)method 
 					error: (NSCalculationError)error 
 				  leftOperand: (NSDecimalNumber*)leftOperand 
 				 rightOperand: (NSDecimalNumber*)rightOperand; 
+
+/**
+ *  Specifies how [NSDecimalNumber]'s <code>decimalNumberBy...</code> methods
+ *  round their return values.  This should be set to one of the following
+ *  constants:
+ *  <deflist>
+ *  <term><code>NSRoundDown</code></term>
+ *  <desc>Always round down.</desc>
+ *  <term><code>NSRoundUp</code></term>
+ *  <desc>Always round up.</desc>
+ *  <term><code>NSRoundPlain</code></term>
+ *  <desc>Round to the closest possible return value.  Halfway (e.g. .5)
+ *  rounds up for positive numbers, down for negative (towards larger absolute
+ *  value).</desc>
+ *  <term><code>NSRoundBankers</code></term>
+ *  <desc>Round to the closest possible return value, but halfway (e.g. .5)
+ *  rounds towards  possibility whose last digit is even.</desc>
+ * </deflist>
+ */
 - (NSRoundingMode) roundingMode;
+
+/**
+ *  Specifies the precision of the values returned by [NSDecimalNumber]'s
+ *  <code>decimalNumberBy...</code> methods, in terms of the number of
+ *  digits allowed after the decimal point.  This can be negative, implying
+ *  that the precision should be, e.g., 100's, 1000's, etc..  For unlimited
+ *  precision, set to <code>NSDecimalNoScale</code>.
+ */
 - (short) scale;
 @end
 
+/**
+ *  A utility class adopting [NSDecimalNumberBehaviors] protocol.  Can be used
+ *  to control [NSDecimalNumber] rounding and exception-handling behavior, by
+ *  passing an instance as an argument to any [NSDecimalNumber] method ending
+ *  with <code>...Behavior:</code>.
+ */
 @interface	NSDecimalNumberHandler : NSObject <NSDecimalNumberBehaviors>
 {
   NSRoundingMode _roundingMode;
@@ -52,7 +124,19 @@
   BOOL _raiseOnDivideByZero;
 }
 
+/**
+ *  Provides an instance implementing the default behavior for the
+ *  [NSDecimalNumber] class.  38 decimal digits, rounded to closest return
+ *  value (<code>NSRoundPlain</code>).  Exceptions raised on overflow,
+ *  underflow, and divide by zero.
+ */
 + (id)defaultDecimalNumberHandler;
+
+/**
+ * Constructor setting all behavior.  (For more precise control over error
+ * handling, create your own class implementing the [NSDecimalNumberBehaviors]
+ * protocol.)
+ */
 + (id)decimalNumberHandlerWithRoundingMode:(NSRoundingMode)roundingMode 
 				     scale:(short)scale
 			  raiseOnExactness:(BOOL)raiseOnExactness 
@@ -60,6 +144,11 @@
 			  raiseOnUnderflow:(BOOL)raiseOnUnderflow
 		       raiseOnDivideByZero:(BOOL)raiseOnDivideByZero;
 
+/**
+ * Initializor setting all behavior.  (For more precise control over error
+ * handling, create your own class implementing the [NSDecimalNumberBehaviors]
+ * protocol.)
+ */
 - (id)initWithRoundingMode:(NSRoundingMode)roundingMode 
 		     scale:(short)scale 
 	  raiseOnExactness:(BOOL)raiseOnExactness
@@ -68,67 +157,249 @@
        raiseOnDivideByZero:(BOOL)raiseOnDivideByZero;
 @end
 
+/**
+ *  <p>Class that implements a number of methods for performing decimal
+ *  arithmetic to arbitrary precision. The behavior in terms of rounding
+ *  choices and exception handling may be customized using the
+ *  [NSDecimalNumberHandler] class, and defaults to
+ *  [NSDecimalNumberHandler+defaultDecimalNumberHandler].</p>
+ *
+ *  <p>Equivalent functionality to the <code>NSDecimalNumber</code> class may
+ *  be accessed through functions, mostly named <code>NSDecimalXXX</code>,
+ *  e.g., NSDecimalMin().  Both the class and the functions use a structure
+ *  called <code>NSDecimal</code>.</p>
+ *
+ *  <p>Note that instances of <code>NSDecimalNumber</code> are immutable.</p>
+ */
 @interface	NSDecimalNumber : NSNumber <NSDecimalNumberBehaviors>
 {
   NSDecimal data;
 }
 
+/**
+ *  Returns the default rounding/precision/exception handling behavior, which
+ *  is same as [NSDecimalNumberHandler+defaultDecimalNumberHandler] unless it
+ *  has been explicitly set otherwise.
+ */
 + (id <NSDecimalNumberBehaviors>)defaultBehavior;
+
+/**
+ *  Sets the default rounding/precision/exception handling behavior to the
+ *  given behavior.  If this is not called, behavior defaults to
+ *  [NSDecimalNumberHandler+defaultDecimalNumberHandler].
+ */
 + (void)setDefaultBehavior:(id <NSDecimalNumberBehaviors>)behavior;
 
+/**
+ *  Return maximum positive value that can be represented.
+ */
 + (NSDecimalNumber *)maximumDecimalNumber;
+
+/**
+ *  Return minimum negative value (<em>not</em> the smallest positive value)
+ *  that can be represented.
+ */
 + (NSDecimalNumber *)minimumDecimalNumber;
+
+/**
+ *  Return a fixed value representing an NaN.
+ */
 + (NSDecimalNumber *)notANumber;
+
+/**
+ *  Return a constant object with a value of one.
+ */
 + (NSDecimalNumber *)one;
+
+/**
+ *  Return a constant object with a value of zero.
+ */
 + (NSDecimalNumber *)zero;
 
+/**
+ *  New instance with given value.  Note an NSDecimal may be created using the
+ *  function NSDecimalFromString().
+ */
 + (NSDecimalNumber *)decimalNumberWithDecimal:(NSDecimal)decimal;
+
+/**
+ *  New instance by component.  Note that the precision of this initializer is
+ *  limited.
+ */
 + (NSDecimalNumber *)decimalNumberWithMantissa:(unsigned long long)mantissa 
 				      exponent:(short)exponent
 				    isNegative:(BOOL)isNegative;
+
+/**
+ *  New instance from string.  Arbitrary precision is preserved, though calling
+ *  one of the <code>decimalNumberBy...</code> methods will return a result
+ *  constrained by the current <em><code>scale</code></em>.  Number format
+ *  is parsed according to current default locale.
+ */
 + (NSDecimalNumber *)decimalNumberWithString:(NSString *)numericString;
+
+/**
+ *  New instance from string.  Arbitrary precision is preserved, though calling
+ *  one of the <code>decimalNumberBy...</code> methods will return a result
+ *  constrained by the current <em><code>scale</code></em>.  Number format
+ *  is parsed according to given locale.
+ */
 + (NSDecimalNumber *)decimalNumberWithString:(NSString *)numericString 
 				      locale:(NSDictionary *)locale;
 
+/**
+ *  Initialize with given value.  Note an NSDecimal may be created using the
+ *  function NSDecimalFromString().
+ */
 - (id)initWithDecimal:(NSDecimal)decimal;
+
+/**
+ *  Initialize by component.  Note that the precision of this initializer is
+ *  limited.
+ */
 - (id)initWithMantissa:(unsigned long long)mantissa 
 	      exponent:(short)exponent 
 	    isNegative:(BOOL)flag;
+
+/**
+ *  Initialize from string.  Arbitrary precision is preserved, though calling
+ *  one of the <code>decimalNumberBy...</code> methods will return a result
+ *  constrained by the current <em><code>scale</code></em>.  Number format
+ *  is parsed according to current default locale.
+ */
 - (id)initWithString:(NSString *)numberValue;
+
+/**
+ *  Initialize from string.  Arbitrary precision is preserved, though calling
+ *  one of the <code>decimalNumberBy...</code> methods will return a result
+ *  constrained by the current <em><code>scale</code></em>.  Number format
+ *  is parsed according to given locale.
+ */
 - (id)initWithString:(NSString *)numberValue 
 	      locale:(NSDictionary *)locale;
 
+/**
+ *  Returns the Objective-C type (<code>@encode(...)</code> compatible) of the
+ *  data contained <code>NSDecimalNumber</code>, which is by convention "d"
+ *  (for double), even though this is not strictly accurate.
+ */
 - (const char *)objCType;
 
+/**
+ *  Return underlying value as an <code>NSDecimal</code> structure.
+ */
 - (NSDecimal)decimalValue;
+
+/**
+ *  Returns string version of number formatted accordng to locale.
+ */
 - (NSString *)descriptionWithLocale:(NSDictionary *)locale;
+
+/**
+ *  Returns underlying value as a <code>double</code>, which may be an
+ *  approximation if precision greater than the default of 38.
+ */
 - (double)doubleValue;
 
+
+/**
+ *  Compares with other number, returning less, greater, or equal.
+ */
 - (NSComparisonResult)compare:(NSNumber *)decimalNumber;
 
+/**
+ *  Adds self to decimalNumber and returns new result, using +defaultBehavior
+ *  for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber;
+
+/**
+ *  Adds self to decimalNumber and returns new result, using given behavior
+ *  for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber 
 			      withBehavior:(id<NSDecimalNumberBehaviors>)behavior;
+
+/**
+ *  Divides self by decimalNumber and returns new result, using +defaultBehavior
+ *  for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber;
+
+/**
+ *  Divides self by decimalNumber and returns new result, using given behavior
+ *  for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber 
 				  withBehavior:(id <NSDecimalNumberBehaviors>)behavior;
+
+/**
+ *  Multiplies self by decimalNumber and returns new result, using
+ *  +defaultBehavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber;
+
+/**
+ *  Multiplies self by decimalNumber and returns new result, using given
+ *  behavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber 
 				     withBehavior:(id <NSDecimalNumberBehaviors>)behavior;
+
+/**
+ *  Multiplies self by given power of 10 and returns new result, using
+ *  +defaultBehavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power;
+
+/**
+ *  Multiplies self by given power of 10 and returns new result, using given
+ *  behavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power 
 					      withBehavior:(id <NSDecimalNumberBehaviors>)behavior;
+
+/**
+ *  Raises self to given positive integer power and returns new result, using
+ *  +defaultBehavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByRaisingToPower:(unsigned)power;
+
+/**
+ *  Raises self to given positive integer power and returns new result, using
+ *  given behavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberByRaisingToPower:(unsigned)power 
 				      withBehavior:(id <NSDecimalNumberBehaviors>)behavior;
-- (NSDecimalNumber *)decimalNumberByRoundingAccordingToBehavior:(id <NSDecimalNumberBehaviors>)behavior;
+
+/**
+ *  Subtracts decimalNumber from self and returns new result, using
+ *  +defaultBehavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberBySubtracting:(NSDecimalNumber *)decimalNumber;
+
+/**
+ *  Subtracts decimalNumber from self and returns new result, using given
+ *  behavior for rounding/precision/error handling.
+ */
 - (NSDecimalNumber *)decimalNumberBySubtracting:(NSDecimalNumber *)decimalNumber 
 				   withBehavior:(id <NSDecimalNumberBehaviors>)behavior;
 
+/**
+ *  Returns rounded version of underlying decimal.
+ */
+- (NSDecimalNumber *)decimalNumberByRoundingAccordingToBehavior:(id <NSDecimalNumberBehaviors>)behavior;
+
 @end
 
+/**
+ *  Interface for obtaining an NSDecimalNumber value from an ordinary
+ *  NSNumber.
+ */
 @interface NSNumber (NSDecimalNumber)
+/**
+ *  Obtaining an NSDecimalNumber version of an ordinary NSNumber.
+ */
 - (NSDecimal) decimalValue;
 @end
 

Headers/Foundation/NSError.h

@@ -58,8 +58,9 @@ GS_EXPORT NSString* const NSOSStatusErrorDomain;
 GS_EXPORT NSString* const NSPOSIXErrorDomain;
 
 /**
- * Error information class
+ * Error information class.
  */
+// TODO: document what this is for, especially since it's not in OS X
 @interface NSError : NSObject <NSCopying, NSCoding>
 {
 @private
@@ -89,7 +90,7 @@ GS_EXPORT NSString* const NSPOSIXErrorDomain;
 
 /** <init />
  * Initialises the receiver using the supplied domain, code, and info.<br />
- * The domain musat be non-nil.
+ * The domain must be non-nil.
  */
 - (id) initWithDomain: (NSString*)aDomain
 		 code: (int)aCode
@@ -105,10 +106,11 @@ GS_EXPORT NSString* const NSPOSIXErrorDomain;
 
 /**
  * Return the user info for this instance (or nil if none is set)<br />
- * The NSLocalizedDescriptionKey should locate a human readable description
+ * The <code>NSLocalizedDescriptionKey</code> should locate a human readable
- * in the dictionary.<br /> 
+ * description in the dictionary.<br /> 
- * The NSUnderlyingErrorKey key should locate an NSError instance if an
+ * The <code>NSUnderlyingErrorKey</code> key should locate an
- * error is available describing any underlying problem.<br />
+ * <code>NSError</code> instance if an error is available describing any
+ * underlying problem.<br />
  */
 - (NSDictionary*) userInfo;
 @end

Headers/Foundation/NSFileHandle.h

@@ -145,7 +145,7 @@ GS_EXPORT NSString * const NSFileHandleOperationException;
 - (BOOL) writeInProgress;
 @end
 
-/*
+/**
  * Where OpenSSL is available, you can use the subclass returned by +sslClass
  * to handle SSL connections.
  *   The -sslAccept method is used to do SSL handlshake and start an

Headers/Foundation/NSFormatter.h

@@ -31,23 +31,88 @@
 
 @class	NSString, NSAttributedString, NSDictionary;
 
+/**
+ *  This abstract class defines the interface for classes that support
+ *  interconversion between strings and objects of various types.  GNUstep
+ *  provides two concrete implementations of this class: [NSDateFormatter]
+ *  and [NSNumberFormatter].  Others may be implemented for specialized
+ *  applications.
+ */
 @interface	NSFormatter : NSObject <NSCopying, NSCoding>
 {
 }
+/**
+ *  This method calls [-stringForObjectValue:] then marks up the string with
+ *  attributes if it should be displayed specially.  For example, in an
+ *  application you may want to display out-of-range dates or numbers in
+ *  italics.  This is an optional method and may return nil to indicate that
+ *  an attributed string is not provided.
+ */
 - (NSAttributedString*) attributedStringForObjectValue: (id)anObject
 				 withDefaultAttributes: (NSDictionary*)attr;
+
+/**
+ * For use in applications where user interactively edits a string.  If the
+ * version of the string for editing purposes should look different from the
+ * string displayed (returned by [-stringForObjectValue:] or
+ * [-attributedStringForObjectValue:withDefaultAttributes:]), return that
+ * here.  For example, the edited string may contain formatting codes or
+ * similar that are not displayed in the final string.  The default
+ * implementation simply returns [-stringForObjectValue:].
+ */
 - (NSString*) editingStringForObjectValue: (id)anObject;
+
+/**
+ *  Primary method for converting a string to an object through parsing.
+ *  anObject and error are output parameters; you should allocate memory for
+ *  one pointer each for the variables passed into these methods.  The
+ *  returned object will have been created through <code>alloc-init</code>.
+ *  If there is a problem with conversion, a constant-string description of
+ *  what went wrong is returned through error, and NO is returned, otherwise
+ *  YES.
+ */
 - (BOOL) getObjectValue: (id*)anObject
 	      forString: (NSString*)string
        errorDescription: (NSString**)error;
+
+/**
+ *  Checks whether partialString <em>could</em>, if it were completed, be
+ *  parsed into a valid object.  newString and error are output parameters;
+ *  you should allocate memory for one pointer each for the variables passed
+ *  into these methods.  This method is set up to be called after every
+ *  keystroke during user editing.  If it returns NO, it optionally returns
+ *  newString to replace what the user was editing; if it doesn't, the editor
+ *  should delete the last character the user typed.
+ */
 - (BOOL) isPartialStringValid: (NSString*)partialString
 	     newEditingString: (NSString**)newString
 	     errorDescription: (NSString**)error;
+
+/**
+ *  Checks whether a change to a string leaves it a valid string that, if it
+ *  were completed, could be parsed into a valid object.  origString contains
+ *  the string before the proposed change, and origSelRange contains the range
+ *  that is updated in the proposed change.  partialStringPtr contains the new
+ *  string to validate and proposedSelRangePtr holds the selection range that
+ *  will be used if the string is accepted or replaced.  Basically, this method
+ *  returns YES if partialStringPtr is valid, otherwise NO and may replace
+ *  partialStringPtr and proposedSelectedRange with improved values, and may
+ *  report the reason in error.
+ */
 - (BOOL) isPartialStringValid: (NSString**)partialStringPtr
         proposedSelectedRange: (NSRange*)proposedSelRangePtr
                originalString: (NSString*)origString
         originalSelectedRange: (NSRange)originalSelRangePtr
              errorDescription: (NSString**)error;
+
+
+/**
+ *  Primary method for converting an object to a string through formatting.
+ *  Object will be converted to string according to the formatter's
+ *  implementation and init parameters.  There is no default handling if the
+ *  class of anObject is not what the formatter expects, and usually nil
+ *  will be returned in this case.
+ */
 - (NSString*) stringForObjectValue: (id)anObject;
 @end
 

Headers/Foundation/NSGeometry.h

@@ -46,7 +46,12 @@
 #define	GS_DEFINED_MIN
 #endif
 
-/* Point definition. */
+/**
+<example>{
+  float x;
+  float y;
+}</example>
+ <p>Represents a 2-d cartesian position.</p> */
 typedef struct _NSPoint NSPoint;
 struct _NSPoint
 {
@@ -55,11 +60,17 @@ struct _NSPoint
 };
 
 #ifndef STRICT_OPENSTEP
+/** Array of NSPoint structs. */
 typedef NSPoint *NSPointArray;
 typedef NSPoint *NSPointPointer;
 #endif
 
-/* Rectangle sizes. */
+/**
+<example>{
+  float width;
+  float height;
+}</example>
+ <p>Floating point rectangle size.</p> */
 typedef struct _NSSize NSSize;
 struct _NSSize
 {
@@ -72,7 +83,13 @@ typedef NSSize *NSSizeArray;
 typedef NSSize *NSSizePointer;
 #endif
 
-/* Rectangle. */
+/**
+<example>{
+  NSPoint origin;
+  NSSize size;
+}</example>
+
+ <p>Rectangle.</p> */
 typedef struct _NSRect NSRect;
 struct _NSRect
 {
@@ -81,6 +98,7 @@ struct _NSRect
 };
 
 #ifndef STRICT_OPENSTEP
+/** Array of NSPoint structs. */
 typedef NSRect *NSRectArray;
 typedef NSRect *NSRectPointer;
 #endif
@@ -95,8 +113,11 @@ enum _NSRectEdge
   NSMaxYEdge
 };
 
+/** Point at 0,0 */
 static const NSPoint NSZeroPoint __attribute__((unused));  /* Zero point. */
+/** Zero-size rectangle at 0,0 */
 static const NSRect NSZeroRect __attribute__((unused));    /* Zero rectangle. */
+/** Zero size */
 static const NSSize NSZeroSize __attribute__((unused));    /* Zero size. */
 
 /**** Function Prototypes ****************************************************/

Headers/Foundation/NSHashTable.h

@@ -47,25 +47,32 @@ typedef void* NSHashTable;
  */
 typedef struct { void *map; void *node; size_t bucket; } NSHashEnumerator;
 
-/** Callback functions. <br />*/
+/** Callback functions for an NSHashTable.  See NSCreateHashTable() . <br />*/
 typedef struct _NSHashTableCallBacks
 {
-  /** hash ... Hashing function. NOTE: Elements with equal values must have
+  /** <code>unsigned int (*hash)(NSHashTable *, const void *)</code> ...
-   * equal hash function values. <br />*/
+   *  Hashing function.  NOTE: Elements with equal values must have equal hash
+   *  function values.  The default if NULL uses the pointer addresses
+   *  directly. <br/>*/
   unsigned int (*hash)(NSHashTable *, const void *);
 
-  /** isEqual ... Comparison function. <br />*/
+  /** <code>BOOL (*isEqual)(NSHashTable *, const void *, const void *)</code>
+   *  ... Comparison function.  The default if NULL uses '<code>==</code>'.
+   *  <br/>*/
   BOOL (*isEqual)(NSHashTable *, const void *, const void *);
 
-  /** retain ... Retaining function called when adding elements
+  /** <code>void (*retain)(NSHashTable *, const void *)</code> ...
-   * to the table. <br />*/
+   *  Retaining function called when adding elements to the table.
+   *  The default if NULL is a no-op (no reference counting). <br/> */
   void (*retain)(NSHashTable *, const void *);
 
-  /** release ... Releasing function called when a data element is
+  /** <code>void (*release)(NSHashTable *, void *)</code> ... Releasing
-   * removed from the table. <br />*/
+   *  function called when a data element is removed from the table.
+   *  The default if NULL is a no-op (no reference counting).<br/>*/
   void (*release)(NSHashTable *, void *);
 
-  /** describe ... Description function. <br />*/
+  /** <code>NSString *(*describe)(NSHashTable *, const void *)</code> ...
+   *  Description function.  The default if NULL prints boilerplate. <br /> */
   NSString *(*describe)(NSHashTable *, const void *);
 } NSHashTableCallBacks;
 

Headers/Foundation/NSHost.h

@@ -27,6 +27,10 @@
 
 @class NSString, NSArray, NSSet;
 
+/**
+ *  Instances of this class encapsulate host information.  Constructors based
+ *  on host name or numeric address are provided.
+ */
 @interface NSHost : NSObject
 {
   @private
@@ -34,51 +38,82 @@
   NSSet	*_addresses;
 }
 
-/*
+/**
- * Get a host object.  Hosts are cached for efficiency.  Only one
+ * Get current host object.
- * shared instance of a host will exist.
- * Addresses must be "Dotted Decimal" strings, e.g.
- *
- * NSHost aHost = [NSHost hostWithAddress:@"192.42.172.1"];
- *
  */
 + (NSHost*) currentHost;
+
+/**
+ *  Get info for host with given DNS name.
+ */
 + (NSHost*) hostWithName: (NSString*)name;
+
+/**
+ *  Get a host object.  Hosts are cached for efficiency.  The address
+ *  must be an IPV4 "dotted decimal" string, e.g.
+ <example>
+  NSHost aHost = [NSHost hostWithAddress:@"192.42.172.1"];
+ </example>
+ */
 + (NSHost*) hostWithAddress: (NSString*)address;
 
-/*
+/**
- * Host cache management
+ * Set host cache management.
  * If enabled, only one object representing each host will be created, and
  * a shared instance will be returned by all methods that return a host.
  */
 + (void) setHostCacheEnabled: (BOOL)flag;
+
+/**
+ * Return host cache management.
+ * If enabled, only one object representing each host will be created, and
+ * a shared instance will be returned by all methods that return a host.
+ */
 + (BOOL) isHostCacheEnabled;
+
+/**
+ * Clear cache of host info instances.
+ */
 + (void) flushHostCache;
 
-/*
+/**
- * Compare hosts
+ * Compare hosts.
  * Hosts are equal if they share at least one address
  */
 - (BOOL) isEqualToHost: (NSHost*) aHost;
 
-/*
+/**
- * Host names.
+ * Return host name.  Chosen arbitrarily if a host has more than one.
- * "name" will return one name (arbitrarily chosen) if a host has several.
  */
 - (NSString*) name;
+
+/**
+ * Return all known names for host.
+ */
 - (NSArray*) names;
 
-/*
+/**
- * Host addresses.
+ * Return host address in "dotted decimal" notation, e.g. "192.42.172.1".
- * Addresses are represented as "Dotted Decimal" strings, e.g.  @"192.42.172.1"
+ * Chosen arbitrarily if a host has more than one.
- * "address" will return one address (arbitrarily chosen) if there are several.
  */
 - (NSString*) address;
+
+/**
+ * Return all known addresses for host in "dotted decimal" notation,
+ * e.g. "192.42.172.1".
+ */
 - (NSArray*) addresses;
 
 @end
 
+/**
+ *  Adds synonym for +currentHost.
+ */
 @interface NSHost (GNUstep)
+
+/**
+ *  Synonym for +currentHost.
+ */
 + (NSHost*) localHost;		/* All local IP addresses	*/
 @end
 

Headers/Foundation/NSKeyedArchiver.h

@@ -37,7 +37,12 @@
 @class NSMutableDictionary, NSMutableData, NSData, NSString;
 
 /**
- * Keyed archiving class
+ *  Implements <em>keyed</em> archiving of object graphs.  This archiver
+ *  should be used instead of [NSArchiver] for new implementations.  Classes
+ *  implementing [NSCoding] should check the [NSCoder-allowsKeyedCoding]
+ *  method and if the response is YES, encode/decode their fields using the
+ *  <code>...forKey:</code> [NSCoder] methods, which provide for more robust
+ *  forwards and backwards compatibility.
  */
 @interface NSKeyedArchiver : NSCoder
 {
@@ -100,16 +105,53 @@
  */
 - (id) delegate;
 
+/**
+ * Encodes aBool and associates the encoded value with aKey.
+ */
 - (void) encodeBool: (BOOL)aBool forKey: (NSString*)aKey;
+
+/**
+ * Encodes the data of the specified length and pointed to by aPointer,
+ * and associates the encoded value with aKey.
+ */
 - (void) encodeBytes: (const uint8_t*)aPointer
 	      length: (unsigned)length
 	      forKey: (NSString*)aKey;
+
+/**
+ * Encodes anObject and associates the encoded value with aKey, but only
+ * if anObject has already been encoded using -encodeObject:forKey:
+ */
 - (void) encodeConditionalObject: (id)anObject forKey: (NSString*)aKey;
+
+/**
+ * Encodes aDouble and associates the encoded value with aKey.
+ */
 - (void) encodeDouble: (double)aDouble forKey: (NSString*)aKey;
+
+/**
+ * Encodes aFloat and associates the encoded value with aKey.
+ */
 - (void) encodeFloat: (float)aFloat forKey: (NSString*)aKey;
+
+/**
+ * Encodes anInteger and associates the encoded value with aKey.
+ */
 - (void) encodeInt: (int)anInteger forKey: (NSString*)aKey;
+
+/**
+ * Encodes anInteger and associates the encoded value with aKey.
+ */
 - (void) encodeInt32: (int32_t)anInteger forKey: (NSString*)aKey;
+
+/**
+ * Encodes anInteger and associates the encoded value with aKey.
+ */
 - (void) encodeInt64: (int64_t)anInteger forKey: (NSString*)aKey;
+
+/**
+ * Encodes anObject and associates the encoded value with aKey.
+ */
 - (void) encodeObject: (id)anObject forKey: (NSString*)aKey;
 
 /**
@@ -159,7 +201,12 @@
 
 
 /**
- * Keyed unarchiving class.
+ *  Implements <em>keyed</em> unarchiving of object graphs.  The keyed archiver
+ *  should be used instead of [NSArchiver] for new implementations.  Classes
+ *  implementing [NSCoding] should check the [NSCoder-allowsKeyedCoding]
+ *  method and if the response is YES, encode/decode their fields using the
+ *  <code>...forKey:</code> [NSCoder] methods, which provide for more robust
+ *  forwards and backwards compatibility.
  */
 @interface NSKeyedUnarchiver : NSCoder
 {
@@ -182,29 +229,132 @@
   NSZone	*_zone;		/* Zone for allocating objs.	*/
 }
 
+/**
+ * Returns class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping.  Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
 + (Class) classForClassName: (NSString*)aString;
+
+/**
+ * Sets class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping.  Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
 + (void) setClass: (Class)aClass forClassName: (NSString*)aString;
+
+/**
+ *  Decodes from byte array in data and returns resulting root object.
+ */
 + (id) unarchiveObjectWithData: (NSData*)data;
+
+/**
+ *  Decodes from file contents at aPath and returns resulting root object.
+ */
 + (id) unarchiveObjectWithFile: (NSString*)aPath;
 
+/**
+ * Returns class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping.  The class as a whole also maintains a
+ * translation map, which is searched on decoding if no match found here.
+ */
 - (Class) classForClassName: (NSString*)aString;
+
+/**
+ * Sets class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping.  Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
 - (BOOL) containsValueForKey: (NSString*)aKey;
+
+/**
+ * Sets class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping.  Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
+- (void) setClass: (Class)aClass forClassName: (NSString*)aString;
+
+/**
+ * Returns a boolean value associated with aKey.  This value must previously
+ * have been encoded using -encodeBool:forKey:
+ */
 - (BOOL) decodeBoolForKey: (NSString*)aKey;
+
+/**
+ * Returns a pointer to a byte array associated with aKey.<br />
+ * Returns the length of the data in aLength.<br />
+ * This value must previously have been encoded using
+ * -encodeBytes:length:forKey:
+ */
 - (const uint8_t*) decodeBytesForKey: (NSString*)aKey
 		      returnedLength: (unsigned*)length;
-- (double) decodeDoubleForKey: (NSString*)aKey;
+
-- (float) decodeFloatForKey: (NSString*)aKey;
-- (int) decodeIntForKey: (NSString*)aKey;
-- (int32_t) decodeInt32ForKey: (NSString*)aKey;
-- (int64_t) decodeInt64ForKey: (NSString*)aKey;
-- (id) decodeObjectForKey: (NSString*)aKey;
 /**
- * returns the delegate of the unarchiver.
+ * Returns a double value associated with aKey.  This value must previously
+ * have been encoded using -encodeDouble:forKey: or -encodeFloat:forKey:
+ */
+- (double) decodeDoubleForKey: (NSString*)aKey;
+
+/**
+ * Returns a float value associated with aKey.  This value must previously
+ * have been encoded using -encodeFloat:forKey: or -encodeDouble:forKey:<br />
+ * Precision may be lost (or an exception raised if the value will not fit
+ * in a float) if the value was encoded using -encodeDouble:forKey:,
+ */
+- (float) decodeFloatForKey: (NSString*)aKey;
+
+/**
+ * Returns an integer value associated with aKey.  This value must previously
+ * have been encoded using -encodeInt:forKey:, -encodeInt32:forKey:, or
+ * -encodeInt64:forKey:.<br />
+ * An exception will be raised if the value does not fit in an integer.
+ */
+- (int) decodeIntForKey: (NSString*)aKey;
+
+/**
+ * Returns a 32-bit integer value associated with aKey.  This value must
+ * previously have been encoded using -encodeInt:forKey:,
+ * -encodeInt32:forKey:, or -encodeInt64:forKey:.<br />
+ * An exception will be raised if the value does not fit in a 32-bit integer.
+ */
+- (int32_t) decodeInt32ForKey: (NSString*)aKey;
+
+/**
+ * Returns a 64-bit integer value associated with aKey.  This value must
+ * previously have been encoded using -encodeInt:forKey:,
+ * -encodeInt32:forKey:, or -encodeInt64:forKey:.
+ */
+- (int64_t) decodeInt64ForKey: (NSString*)aKey;
+
+/**
+ * Returns an object value associated with aKey.  This value must
+ * previously have been encoded using -encodeObject:forKey: or
+ * -encodeConditionalObject:forKey:
+ */
+- (id) decodeObjectForKey: (NSString*)aKey;
+
+/**
+ * Returns the delegate of the unarchiver.
  */
 - (id) delegate;
+
+/**
+ * Tells receiver that you are done retrieving from archive, so the delegate
+ * should be allowed to perform close-up operations.
+ */
 - (void) finishDecoding;
+
+/**
+ * Prepare to read data from key archive (created by [NSKeyedArchiver]).
+ * Be sure to call -finishDecoding when done.
+ */
 - (id) initForReadingWithData: (NSData*)data;
-- (void) setClass: (Class)aClass forClassName: (NSString*)aString;
+
 /**
  * Sets the receivers delegate.  The delegate should conform to the
  * NSObject(NSKeyedUnarchiverDelegate) informal protocol.<br />
@@ -215,10 +365,17 @@
 
 @end
 
+/**
+ * Internal methods.  Do not use.
+ */
 @interface	NSKeyedArchiver (Internal)
 - (void) _encodeArrayOfObjects: (NSArray*)anArray forKey: (NSString*)aKey;
 - (void) _encodePropertyList: (id)anObject forKey: (NSString*)aKey;
 @end
+
+/**
+ * Internal methods.  Do not use.
+ */
 @interface	NSKeyedUnarchiver (Internal)
 - (id) _decodeArrayOfObjectsForKey: (NSString*)aKey;
 - (id) _decodePropertyListForKey: (NSString*)aKey;
@@ -231,7 +388,7 @@ GS_EXPORT NSString * const NSInvalidUnarchiveOperationException;
 
 
 /**
- * Informal protocol implemented by delegates of [NSKeyedArchiver]
+ * Informal protocol implemented by delegates of [NSKeyedArchiver].
  */
 @interface NSObject (NSKeyedArchiverDelegate)
 
@@ -277,7 +434,7 @@ willReplaceObject: (id)anObject
 
 
 /**
- * Informal protocol implemented by delegates of [NSKeyedUnarchiver]
+ * Informal protocol implemented by delegates of [NSKeyedUnarchiver].
  */
 @interface NSObject (NSKeyedUnarchiverDelegate) 
 
@@ -325,7 +482,7 @@ willReplaceObject: (id)anObject
 
 
 /**
- * Methods by which a class may control its archiving by the NSKeyedArchiver
+ * Methods by which a class may control its archiving by the [NSKeyedArchiver].
  */
 @interface NSObject (NSKeyedArchiverObjectSubstitution) 
 
@@ -351,6 +508,10 @@ willReplaceObject: (id)anObject
 
 @end
 
+/**
+ * Methods by which a class may control its unarchiving by the
+ * [NSKeyedArchiver].
+ */
 @interface NSObject (NSKeyedUnarchiverObjectSubstitution) 
 
 /**
@@ -363,34 +524,37 @@ willReplaceObject: (id)anObject
 
 @end
 
+/**
+ *  Methods for encoding/decoding points, rectangles, and sizes.
+ */
 @interface NSCoder (NSGeometryKeyedCoding)
 /**
- * Encodes an NSPoint object.
+ * Encodes an <code>NSPoint</code> object.
  */
 - (void) encodePoint: (NSPoint)aPoint forKey: (NSString*)aKey;
 
 /**
- * Encodes an NSRect object.
+ * Encodes an <code>NSRect</code> object.
  */
 - (void) encodeRect: (NSRect)aRect forKey: (NSString*)aKey;
 
 /**
- * Encodes an NSSize object.
+ * Encodes an <code>NSSize</code> object.
  */
 - (void) encodeSize: (NSSize)aSize forKey: (NSString*)aKey;
 
 /**
- * Decodes an NSPoint object.
+ * Decodes an <code>NSPoint</code> object.
  */
 - (NSPoint) decodePointForKey: (NSString*)aKey;
 
 /**
- * Decodes an NSRect object.
+ * Decodes an <code>NSRect</code> object.
  */
 - (NSRect) decodeRectForKey: (NSString*)aKey;
 
 /**
- * Decodes an NSSize object.
+ * Decodes an <code>NSSize</code> object.
  */
 - (NSSize) decodeSizeForKey: (NSString*)aKey;
 @end

Headers/Foundation/NSLock.h

@@ -33,19 +33,25 @@
 
 #include <Foundation/NSObject.h>
 
-/*
+/**
- * NSLocking protocol
+ * Protocol defining lock and unlock operations.
  */
 @protocol NSLocking
 
+/**
+ *  Block until acquiring lock.
+ */
 - (void) lock;
+
+/**
+ *  Relinquish lock.
+ */
 - (void) unlock;
 
 @end
 
-/*
+/**
- * NSLock class
+ * Simplest lock for protecting critical sections of code.
- * Simplest lock for protecting critical sections of code
  */
 @interface NSLock : NSObject <NSLocking, GCFinalization>
 {
@@ -53,17 +59,32 @@
   void *_mutex;
 }
 
+/**
+ *  Try to acquire lock and return immediately, YES if succeeded, NO if not.
+ */
 - (BOOL) tryLock;
+
+/**
+ *  Try to acquire lock and return before limit, YES if succeeded, NO if not.
+ */
 - (BOOL) lockBeforeDate: (NSDate*)limit;
 
+/**
+ *  Block until acquiring lock.
+ */
 - (void) lock;
+
+/**
+ *  Relinquish lock.
+ */
 - (void) unlock;
 
 @end
 
-/*
+/**
- * NSConditionLock
+ *  Lock that allows user to request it only when an internal integer
- * Allows locking and unlocking to be based upon a condition
+ *  condition is equal to a particular value.  The condition is set on
+ *  initialization and whenever the lock is relinquished.
  */
 @interface NSConditionLock : NSObject <NSLocking, GCFinalization>
 {
@@ -73,39 +94,74 @@
   int   _condition_value;
 }
 
-/*
+/**
- * Initialize lock with condition
+ * Initialize lock with given condition.
  */
 - (id) initWithCondition: (int)value;
 
-/*
+/**
- * Return the current condition of the lock
+ * Return the current condition of the lock.
  */
 - (int) condition;
 
 /*
- * Acquiring and release the lock
+ * Acquiring and releasing the lock.
+ */
+
+/**
+ *  Acquire lock when it is available and the internal condition is equal to
+ *  value.  Blocks until this occurs.
  */
 - (void) lockWhenCondition: (int)value;
+
+/**
+ *  Relinquish the lock, setting internal condition to value.
+ */
 - (void) unlockWithCondition: (int)value;
+
+/**
+ *  Try to acquire lock regardless of condition and return immediately, YES if
+ *  succeeded, NO if not.
+ */
 - (BOOL) tryLock;
+
+/**
+ *  Try to acquire lock if condition is equal to value and return immediately
+ *  in any case, YES if succeeded, NO if not.
+ */
 - (BOOL) tryLockWhenCondition: (int)value;
 
 /*
- * Acquiring the lock with a date condition
+ * Acquiring the lock with a date condition.
+ */
+
+/**
+ *  Try to acquire lock and return before limit, YES if succeeded, NO if not.
  */
 - (BOOL) lockBeforeDate: (NSDate*)limit;
+
+/**
+ *  Try to acquire lock, when internal condition is equal to condition_to_meet,
+ *  and return before limit, YES if succeeded, NO if not.
+ */
 - (BOOL) lockWhenCondition: (int)condition_to_meet
                 beforeDate: (NSDate*)limitDate;
 
+/**
+ *  Block until acquiring lock.
+ */
 - (void) lock;
+
+/**
+ *  Relinquish lock.
+ */
 - (void) unlock;
 
 @end
 
-/*
+
- * NSRecursiveLock
+/**
- * Allows the lock to be recursively acquired by the same thread
+ * Allows the lock to be recursively acquired by the same thread.
  *
  * If the same thread locks the mutex (n) times then that same 
  * thread must also unlock it (n) times before another thread 
@@ -117,10 +173,25 @@
   void *_mutex;
 }
 
+/**
+ *  Try to acquire lock regardless of condition and return immediately, YES if
+ *  succeeded, NO if not.
+ */
 - (BOOL) tryLock;
+
+/**
+ *  Try to acquire lock and return before limit, YES if succeeded, NO if not.
+ */
 - (BOOL) lockBeforeDate: (NSDate*)limit;
 
+/**
+ *  Block until acquiring lock.
+ */
 - (void) lock;
+
+/**
+ *  Relinquish lock.
+ */
 - (void) unlock;
 
 @end
@@ -153,11 +224,63 @@
 #define GS_INITIALIZED_LOCK(IDENT,CLASSNAME) \
            (IDENT != nil ? IDENT : [CLASSNAME newLockAt: &IDENT])
 
+/**
+ *  Defines the <code>newLockAt:</code> method.
+ */
 @interface NSLock (GSCategories)
+/**
+ * Initializes the id pointed to by location
+ * with a new instance of the receiver's class
+ * in a thread safe manner, unless
+ * it has been previously initialized.
+ * Returns the contents pointed to by location.  
+ * The location is considered unintialized if it contains nil.
+ * <br/>
+ * This method is used in the GS_INITIALIZED_LOCK macro
+ * to initialize lock variables when it cannot be insured
+ * that they can be initialized in a thread safe environment.
+ * <example>
+ * NSLock *my_lock = nil;
+ *
+ * void function (void)
+ * {
+ *   [GS_INITIALIZED_LOCK(my_lock, NSLock) lock];
+ *   do_work ();
+ *   [my_lock unlock];
+ * }
+ * 
+ * </example>
+ */
 + (id)newLockAt:(id *)location;
 @end
 
+/**
+ *  Defines the <code>newLockAt:</code> method.
+ */
 @interface NSRecursiveLock (GSCategories)
+/**
+ * Initializes the id pointed to by location
+ * with a new instance of the receiver's class
+ * in a thread safe manner, unless
+ * it has been previously initialized.
+ * Returns the contents pointed to by location.  
+ * The location is considered unintialized if it contains nil.
+ * <br/>
+ * This method is used in the GS_INITIALIZED_LOCK macro
+ * to initialize lock variables when it cannot be insured
+ * that they can be initialized in a thread safe environment.
+ * <example>
+ * NSLock *my_lock = nil;
+ *
+ * void function (void)
+ * {
+ *   [GS_INITIALIZED_LOCK(my_lock, NSRecursiveLock) lock];
+ *   do_work ();
+ *   [my_lock unlock];
+ * }
+ * 
+ * </example>
+ */
 + (id)newLockAt:(id *)location;
 @end
 

Headers/Foundation/NSMapTable.h

@@ -81,7 +81,7 @@ typedef struct _NSMapTableKeyCallBacks
 
   /**
    * Description function. Generates a string describing the key
-   * and does not modify the key itsself.
+   * and does not modify the key itself.
    */ 
   NSString *(*describe)(NSMapTable *, const void *);
 
@@ -115,7 +115,7 @@ struct _NSMapTableValueCallBacks
 
   /**
    * Description function. Generates a string describing the element
-   * and does not modify the element itsself.
+   * and does not modify the element itself.
    */ 
   NSString *(*describe)(NSMapTable *, const void *);
 };

Headers/Foundation/NSMethodSignature.h

@@ -29,12 +29,22 @@
 #include <Foundation/NSObject.h>
 
 #ifndef	STRICT_MACOS_X
-/*
+/**
- *	Info about layout of arguments.
+ *	<p>Info about layout of arguments.
  *	Extended from the original OpenStep version to let us know if the
- *	arg is passed in registers or on the stack.
+ *	arg is passed in registers or on the stack.</p>
  *
- *	NB. This no longer exists in Rhapsody/MacOS.
+ *	<p>NB. This no longer exists in Rhapsody/MacOS.</p>
+ <example>
+typedef struct	{
+  int		offset;
+  unsigned	size;
+  const char	*type;
+  unsigned	align;  // extension, available only ifndef NO_GNUSTEP
+  unsigned	qual;   // extension, available only ifndef NO_GNUSTEP
+  BOOL		isReg;  // extension, available only ifndef NO_GNUSTEP
+} NSArgumentInfo;
+ </example>
  */
 typedef struct	{
   int		offset;
@@ -48,6 +58,19 @@ typedef struct	{
 } NSArgumentInfo;
 #endif
 
+/**
+ * <p>Class encapsulating type information for method arguments and return
+ * value.  It is used as a component of [NSInvocation] to implement message
+ * forwarding, such as within the distributed objects framework.  Instances
+ * can be obtained from the [NSObject] method
+ * [NSObject-methodSignatureForSelector:].</p>
+ *
+ * <p>Basically, types are represented as Objective-C <code>@encode(...)</code>
+ * compatible strings, together with size information.  The arguments are
+ * numbered starting from 0, including the implicit arguments
+ * <code><em>self</em></code> (type <code>id</code>, at position 0) and
+ * <code><em>_cmd</em></code> (type <code>SEL</code>, at position 1).</p>
+ */
 @interface NSMethodSignature : NSObject
 {
   const char		*_methodTypes;
@@ -60,23 +83,78 @@ typedef struct	{
 #endif
 }
 
+/**
+ * Build a method signature directly from string description of return type and
+ * argument types, using the Objective-C <code>@encode(...)</code> type codes.
+ */
 + (NSMethodSignature*) signatureWithObjCTypes: (const char*)t;
 
 #ifndef	STRICT_MACOS_X
+/**
+ * Returns full information on given argument.  Indices start at 0.  Provide
+ * -1 to get info on return value.
+ */
 - (NSArgumentInfo) argumentInfoAtIndex: (unsigned)index;
 #endif
+
+/**
+ * Number of bytes that the full set of arguments occupies on the stack, which
+ * is platformt(hardware)-dependent.
+ */
 - (unsigned) frameLength;
+
+/**
+ * Returns Objective-C <code>@encode(...)</code> compatible string.  Arguments
+ * are numbered starting from 0, including the implicit arguments
+ * <code><em>self</em></code> (type <code>id</code>, at position 0) and
+ * <code><em>_cmd</em></code> (type <code>SEL</code>, at position 1).
+ */
 - (const char*) getArgumentTypeAtIndex: (unsigned)index;
+
+/**
+ * Pertains to distributed objects; method is asynchronous when invoked and
+ * return should not be waited for.
+ */
 - (BOOL) isOneway;
+
+/**
+ * Number of bytes that the return value occupies on the stack, which is
+ * platformt(hardware)-dependent.
+ */
 - (unsigned) methodReturnLength;
+
+/**
+ * Returns Objective-C <code>@encode(...)</code> compatible string.  Arguments
+ * are numbered starting from 0, including the implicit arguments
+ * <code><em>self</em></code> (type <code>id</code>, at position 0) and
+ * <code><em>_cmd</em></code> (type <code>SEL</code>, at position 1).
+ */
 - (const char*) methodReturnType;
+
+/**
+ * Returns number of arguments to method, including the implicit
+ * <code><em>self</em></code> and <code><em>_cmd</em></code>.
+ */
 - (unsigned) numberOfArguments;
 
 @end
 
 #ifndef	NO_GNUSTEP
+/**
+ * Declares a convenience method for getting the entire array of raw type and
+ * size information.
+ */
 @interface NSMethodSignature(GNUstep)
+/**
+ * Convenience method for getting the entire array of raw type and size
+ * information.
+ */
 - (NSArgumentInfo*) methodInfo;
+
+/**
+ * Returns a string containing all Objective-C
+ * <code>@encode(...)</code> compatible type information.
+ */
 - (const char*) methodType;
 @end
 #endif

Headers/Foundation/NSNotification.h

@@ -85,19 +85,25 @@
 
 #ifndef	NO_GNUSTEP
 
+/**
+ * Defines some extensions for maximising posting performance - these options
+ * are NOT adjustable for the default notification center.
+ *
+ */
 @interface NSNotificationCenter (GNUstep)
-/*
+
- * Extensions for maximising posting performance - these options are
+/**
- * NOT adjustable for the default notification center.
- *
- * You can disable locking in a multi-threaded program if you KNOW that only
- * one thread will ever use the notification center.
- *
  * You can turn on 'immutability' if you KNOW that the posting of a
  * notification will never result in an attempt to modify the center.
  * In this case, the center can optimise delivery of notifications.
  */
 - (BOOL) setImmutableInPost: (BOOL)flag;
+
+/**
+ *
+ * You can disable locking in a multi-threaded program if you KNOW that only
+ * one thread will ever use the notification center.
+ */
 - (BOOL) setLockingDisabled: (BOOL)flag;
 @end
 #endif

Headers/Foundation/NSNumberFormatter.h

@@ -33,6 +33,42 @@
 
 @class	NSString, NSAttributedString, NSDictionary;
 
+/**
+ * <p><em><strong>This class is currently not implemented in GNUstep!  All set
+ * methods will work, but stringForObject: will ignore the format completely.
+ * The documentation below describes what the behavior SHOULD
+ * be...</strong></em></p>
+ *
+ * <p>A specialization of the [NSFormatter] class for generating string
+ * representations of numbers ([NSNumber] and [NSDecimalNumber] instances) and
+ * for parsing numeric values in strings.</p>
+ *
+ *  <p>See the [NSFormatter] documentation for description of the basic methods
+ *  for formatting and parsing that are available.</p>
+ *
+ * <p>There are no convenience initializers or constructors for this class.
+ *  Instead, to obtain an instance, call alloc init and then -setFormat: .</p>
+ *
+ *  <p>The basic format of a format string uses "#" signs to represent digits,
+ *  and other characters to represent themselves, in a context-dependent way.
+ *  Thus, for example, <code>@"#,###.00"</code> means to print the number
+ *  ending in .00 if it has no decimal part, otherwise print two decimal
+ *  places, and to print one comma if it is greater than 1000.  Thus, 1000
+ *  prints as "1,000.00", and 1444555.979 prints as "1444,555.98" (see
+ *  -setRoundingBehavior:).</p>
+ *
+ * <p>After setting the format, you may change the thousands separator and
+ * decimal point using set methods, or by calling -setLocalizesFormat: .</p>
+ *
+ * <p>You may set separate formats to be used for positive numbers, negative
+ * numbers, and zero independently.</p>
+ *
+ * <p>In addition, this class supports attributed strings (see
+ * [NSAttributedString]), so that you can specify font and color attributes,
+ * among others, to display aspects of a number.  You can assign specific sets
+ * of attributes for positive and negative numbers, and for specific cases
+ * including 0, NaN, and nil... </p>
+ */
 @interface NSNumberFormatter: NSFormatter
 {
   BOOL _hasThousandSeparators;
@@ -53,45 +89,207 @@
 }
 
 // Format
+/**
+ * Returns the format string this instance was initialized with.
+ */
 - (NSString*) format;
+
+/**
+ * Sets format string.  See class description for more information.
+ */
 - (void) setFormat: (NSString*)aFormat;
+
+/**
+ * Returns whether this format should defer to the locale in determining
+ * thousands separator and decimal point.  The default is to NOT localize.
+ */
 - (BOOL) localizesFormat;
+
+/**
+ * Set whether this format should defer to the locale in determining thousands
+ * separator and decimal point.  The default is to NOT localize.
+ */
 - (void) setLocalizesFormat: (BOOL)flag;
+
+/**
+ * Returns format used for negative numbers.
+ */
 - (NSString*) negativeFormat;
+
+/**
+ * Sets format used for negative numbers.  See class description for more
+ * information.
+ */
 - (void) setNegativeFormat: (NSString*)aFormat;
+
+/**
+ * Returns format used for positive numbers.
+ */
 - (NSString*) positiveFormat;
+
+/**
+ * Sets format used for positive numbers.  See class description for more
+ * information.
+ */
 - (void) setPositiveFormat: (NSString*)aFormat;
 
+
 // Attributed Strings
+/**
+ *  Returns the exact attributed string used for nil values.  By default this
+ *  is an empty string.
+ */
 - (NSAttributedString*) attributedStringForNil;
+
+/**
+ *  Sets the exact attributed string used for nil values.  By default this
+ *  is an empty string.
+ */
 - (void) setAttributedStringForNil: (NSAttributedString*)newAttributedString;
+
+/**
+ *  Returns the exact attributed string used for NaN values.  By default this
+ *  is the string "NaN" with no attributes.
+ */
 - (NSAttributedString*) attributedStringForNotANumber;
+
+/**
+ *  Sets the exact attributed string used for NaN values.  By default this
+ *  is the string "NaN" with no attributes.
+ */
 - (void) setAttributedStringForNotANumber: (NSAttributedString*)newAttributedString;
+
+/**
+ *  Returns the exact attributed string used for zero values.  By default this
+ *  is based on the format for zero values, if set, or the format for positive
+ *  values otherwise.
+ */
 - (NSAttributedString*) attributedStringForZero;
+
+/**
+ *  Sets the exact attributed string used for zero values.  By default this
+ *  is based on the format for zero values, if set, or the format for positive
+ *  values otherwise.
+ */
 - (void) setAttributedStringForZero: (NSAttributedString*)newAttributedString;
+
+/**
+ * Returns the attributes to apply to negative values (whole string), when
+ * -attributedStringForObjectValue:withDefaultAttributes: is called.  Default
+ * is none.
+ */
 - (NSDictionary*) textAttributesForNegativeValues;
+
+/**
+ * Sets the attributes to apply to negative values (whole string), when
+ * -attributedStringForObjectValue:withDefaultAttributes: is called.  Default
+ * is none.
+ */
 - (void) setTextAttributesForNegativeValues: (NSDictionary*)newAttributes;
+
+/**
+ * Returns the attributes to apply to positive values (whole string), when
+ * -attributedStringForObjectValue:withDefaultAttributes: is called.  Default
+ * is none.
+ */
 - (NSDictionary*) textAttributesForPositiveValues;
+
+/**
+ * Sets the attributes to apply to positive values (whole string), when
+ * -attributedStringForObjectValue:withDefaultAttributes: is called.  Default
+ * is none.
+ */
 - (void) setTextAttributesForPositiveValues: (NSDictionary*)newAttributes;
 
-// Rounding
+
+// Rounding.. this should be communicated as id<NSDecimalNumberBehaviors>,
+// not NSDecimalNumberHandler, but this is the way OpenStep and OS X do it..
+
+/**
+ * Returns object specifying the rounding behavior used when truncating
+ * decimal digits in formats.  Default is
+ * [NSDecimalNumberHandler+defaultDecimalNumberHandler].
+ */
 - (NSDecimalNumberHandler*) roundingBehavior;
+
+/**
+ * Sets object specifying the rounding behavior used when truncating
+ * decimal digits in formats.  Default is
+ * [NSDecimalNumberHandler+defaultDecimalNumberHandler].
+ */
 - (void) setRoundingBehavior: (NSDecimalNumberHandler*)newRoundingBehavior;
 
 // Separators
+
+/**
+ * Returns whether thousands separator should be used, regardless of whether
+ * it is set in format.  (Default is YES if explicitly set in format.)
+ */
 - (BOOL) hasThousandSeparators;
+
+/**
+ * Sets whether thousands separator should be used, regardless of whether
+ * it is set in format.  (Default is YES if explicitly set in format.)
+ */
 - (void) setHasThousandSeparators: (BOOL)flag;
+
+
+/**
+ * Returns thousands separator used; default is ','.
+ */
 - (NSString*) thousandSeparator;
+
+/**
+ * Sets thousands separator used; default is ','.
+ */
 - (void) setThousandSeparator: (NSString*)newSeparator;
+
+/**
+ * Returns whether number parsing will accept floating point values or generate
+ * an exception (only int values are valid).  Default is YES.
+ */
 - (BOOL) allowsFloats;
+
+/**
+ * Sets whether number parsing will accept floating point values or generate
+ * an exception (only int values are valid).  Default is YES.
+ */
 - (void) setAllowsFloats: (BOOL)flag;
+
+/**
+ * Returns thousands separator used; default is '.'.
+ */
 - (NSString*) decimalSeparator;
+
+/**
+ * Sets thousands separator used; default is '.'.
+ */
 - (void) setDecimalSeparator: (NSString*)newSeparator;
 
 // Maximum/minimum
+
+/**
+ * Returns maximum value that will be accepted as valid in number parsing.
+ * Default is none.
+ */
 - (NSDecimalNumber*) maximum;
+
+/**
+ * Sets maximum value that will be accepted as valid in number parsing.
+ * Default is none.
+ */
 - (void) setMaximum: (NSDecimalNumber*)aMaximum;
+
+/**
+ * Returns minimum value that will be accepted as valid in number parsing.
+ * Default is none.
+ */
 - (NSDecimalNumber*) minimum;
+
+/**
+ * Sets minimum value that will be accepted as valid in number parsing.
+ * Default is none.
+ */
 - (void) setMinimum: (NSDecimalNumber*)aMinimum;
 
 @end

Headers/Foundation/NSObjCRuntime.h

@@ -39,9 +39,11 @@ GS_EXPORT const char	*NSGetSizeAndAlignment(const char *typePtr,
 
 #ifndef	NO_GNUSTEP
 /* Logging */
-/* OpenStep spec states that log messages go to stderr, but just in case
+/**
-   someone wants them to go somewhere else, they can implement a function
+ *  OpenStep spec states that log messages go to stderr, but just in case
-   like this */
+ *  someone wants them to go somewhere else, they can implement a function
+ *  like this.
+ */
 typedef void NSLog_printf_handler (NSString* message);
 GS_EXPORT NSLog_printf_handler	*_NSLog_printf_handler;
 GS_EXPORT int	_NSLogDescriptor;

Headers/Foundation/NSObject.h

@@ -140,13 +140,33 @@
  * to remote processes via the Distributed Objects mechanism.
  */
 @protocol NSCoding
+
+/**
+ * Called when it is time for receiver to be serialized for writing to an
+ * archive or network connection.  Receiver should record all of its instance
+ * variables using methods on aCoder.  See documentation for [NSCoder],
+ * [NSArchiver], [NSKeyedArchiver], and/or [NSPortCoder] for more information.
+ */
 - (void) encodeWithCoder: (NSCoder*)aCoder;
+
+/**
+ * Called on a freshly allocated receiver when it is time to reconstitute from
+ * serialized bytes in an archive or from a network connection.  Receiver
+ * should load all of its instance variables using methods on aCoder.  See
+ * documentation for [NSCoder], [NSUnarchiver], [NSKeyedUnarchiver], and/or
+ * [NSPortCoder] for more information.
+ */
 - (id) initWithCoder: (NSCoder*)aDecoder;
 @end
 
 
 @interface NSObject <NSObject>
 {
+ /**
+  * Points to instance's class.  Used by runtime to access method
+  * implementations, etc..  Set in +alloc, Unlike other instance variables,
+  * which are cleared there.
+  */
   Class isa;
 }
 
@@ -260,6 +280,11 @@ NSExtraRefCount(id anObject);
 GS_EXPORT void
 NSIncrementExtraRefCount(id anObject);
 
+/**
+ * Contains values <code>NSOrderedSame</code>, <code>NSOrderedAscending</code>
+ * <code>NSOrderedDescending</code>, for left hand side equals, less than, or
+ * greater than right hand side.
+ */
 typedef enum _NSComparisonResult 
 {
   NSOrderedAscending = -1, NSOrderedSame, NSOrderedDescending
@@ -291,11 +316,38 @@ GS_EXPORT NSRecursiveLock *gnustep_global_lock;
 - (id) write: (TypedStream*)aStream;
 @end
 
+/**
+ * Provides a number of GNUstep-specific methods that are used to aid
+ * implementation of the Base library.
+ */
 @interface NSObject (GSCategories)
+
+/**
+ * Message sent when an implementation wants to explicitly exclude a method
+ * (but cannot due to compiler constraint), and wants to make sure it is not
+ * called by mistake.  Default implementation raises an exception at runtime.
+ */
 - notImplemented:(SEL)aSel;
+
+/**
+ * Message sent when an implementation wants to explicitly require a subclass
+ * to implement a method (but cannot at compile time since there is no
+ * <code>abstract</code> keyword in Objective-C).  Default implementation
+ * raises an exception at runtime to alert developer that he/she forgot to
+ * override a method.
+ */
 - (id) subclassResponsibility: (SEL)aSel;
+
+/**
+ * Message sent when an implementation wants to explicitly exclude a method
+ * (but cannot due to compiler constraint) and forbid that subclasses
+ * implement it.  Default implementation raises an exception at runtime.  If a
+ * subclass <em>does</em> implement this method, however, the superclass's
+ * implementation will not be called, so this is not a perfect mechanism.
+ */
 - (id) shouldNotImplement: (SEL)aSel;
-/*
+
+/**
   WARNING: The -compare: method for NSObject is deprecated
            due to subclasses declaring the same selector with
            conflicting signatures.
@@ -310,23 +362,53 @@ GS_EXPORT NSRecursiveLock *gnustep_global_lock;
 
 #endif
 
-/*
+/**
  *	Protocol for garbage collection finalization - same as libFoundation
  *	for compatibility.
  */
 @protocol       GCFinalization
+/**
+ *  Called before receiver is deallocated by garbage collector.  If you want
+ *  to do anything special before [NSObject -dealloc] is called, do it here.
+ */
 - (void) gcFinalize;
 @end
 
 #include <Foundation/NSDate.h>
+/**
+ *  Declares some methods for sending messages to self after a fixed delay.
+ *  (These methods <em>are</em> in OpenStep and OS X.)
+ */
 @interface NSObject (TimedPerformers)
+
+/**
+ * Cancels any perform operations set up for the specified target
+ * in the current run loop.
+ */
 + (void) cancelPreviousPerformRequestsWithTarget: (id)obj;
+
+/**
+ * Cancels any perform operations set up for the specified target
+ * in the current loop, but only if the value of aSelector and argument
+ * with which the performs were set up match those supplied.<br />
+ * Matching of the argument may be either by pointer equality or by
+ * use of the [NSObject-isEqual:] method.
+ */
 + (void) cancelPreviousPerformRequestsWithTarget: (id)obj
 					selector: (SEL)s
 					  object: (id)arg;
+/**
+ * Sets given message to be sent to this instance after given delay,
+ * in any run loop mode.  See [NSRunLoop].
+ */
 - (void) performSelector: (SEL)s
 	      withObject: (id)arg
 	      afterDelay: (NSTimeInterval)seconds;
+
+/**
+ * Sets given message to be sent to this instance after given delay,
+ * in given run loop modes.  See [NSRunLoop].
+ */
 - (void) performSelector: (SEL)s
 	      withObject: (id)arg
 	      afterDelay: (NSTimeInterval)seconds

Headers/Foundation/NSPort.h

@@ -49,38 +49,104 @@
 
 GS_EXPORT NSString * const NSPortTimeoutException; /* OPENSTEP */
 
+/**
+ * <p><code>NSPort</code> is an abstract class defining interfaces underlying
+ * communications in the distributed objects framework.  Each side of a
+ * connection will have an <code>NSPort</code> object, responsible for sending
+ * and receiving [NSPortMessage]s, which are then passed to delegates when
+ * received.  The <code>NSPort</code> must be added to the [NSRunLoop] as an
+ * input source.</p>
+ *
+ * <p>This class also implements the functionality of the
+ * <code><em>NSMachPort</em></code> class on OS X.</p>
+ */
 @interface NSPort : NSObject <NSCoding, NSCopying>
 {
   BOOL		_is_valid;
   id		_delegate;
 }
 
+/**
+ * Basic constructor returns object capable of send and receive.
+ */
 + (NSPort*) port;
+
+/**
+ * NSMachPort compatibility method.
+ */
 + (NSPort*) portWithMachPort: (int)machPort;
 
+/**
+ *  Returns the object that received messages will be passed off to.
+ */
 - (id) delegate;
 
-- (id) init;
+/**
-- (id) initWithMachPort: (int)machPort;
+ *  Sets the object that received messages will be passed off to.
-
+ */
-- (void) invalidate;
-- (BOOL) isValid;
-- (int) machPort;
 - (void) setDelegate: (id)anObject;
 
+/**
+ * Basic initializer sets up object capable of send and receive.
+ */
+- (id) init;
+
+/**
+ * NSMachPort compatibility method.
+ */
+- (id) initWithMachPort: (int)machPort;
+
+/**
+ * NSMachPort compatibility.
+ */
+- (int) machPort;
+
+/**
+ * Mark port as invalid, deregister with listeners and cease further network
+ * operations.  Subclasses should override and call super.
+ */
+- (void) invalidate;
+
+/**
+ * Returns whether port has been marked invalid.
+ */
+- (BOOL) isValid;
+
 #ifndef	STRICT_OPENSTEP
+/**
+ * Adds to run loop as input source to be notified for input in given mode.
+ * This method is for use by subclasses.
+ */
 - (void) addConnection: (NSConnection*)aConnection
 	     toRunLoop: (NSRunLoop*)aLoop
 	       forMode: (NSString*)aMode;
+
+/**
+ * Removes from run loop as input source to be notified for input in given mode.
+ * This method is for use by subclasses.
+ */
 - (void) removeConnection: (NSConnection*)aConnection
 	      fromRunLoop: (NSRunLoop*)aLoop
 		  forMode: (NSString*)aMode;
+
+/**
+ * Returns amount of space used for header info at beginning of messages.
+ * Subclasses should override (this implementation returns 0).
+ */
 - (unsigned) reservedSpaceLength;
+
+/**
+ * Internal method for sending message, for use by subclasses.
+ */
 - (BOOL) sendBeforeDate: (NSDate*)when
 		  msgid: (int)msgid
 	     components: (NSMutableArray*)components
 		   from: (NSPort*)receivingPort
 	       reserved: (unsigned)length;
+
+/**
+ * Internal method for sending message, for use by subclasses.
+ */
 - (BOOL) sendBeforeDate: (NSDate*)when
 	     components: (NSMutableArray*)components
 		   from: (NSPort*)receivingPort
@@ -89,7 +155,11 @@ GS_EXPORT NSString * const NSPortTimeoutException; /* OPENSTEP */
 @end
 
 #ifndef	NO_GNUSTEP
+/**
+ * Stubs for backward compatibility.  Do not use.
+ */
 @interface NSPort (GNUstep)
+//PENDING: none of this is implemented.. should it be removed?
 - (void) close;
 + (Class) outPacketClass;
 - (Class) outPacketClass;
@@ -105,6 +175,15 @@ GS_EXPORT	NSString*	NSPortDidBecomeInvalidNotification;
 typedef SOCKET NSSocketNativeHandle;
 
 @class GSTcpHandle;
+
+/**
+ *  <p>An [NSPort] implementation for network object communications based on
+ *  BSD sockets.  Can be used for interthread/interprocess
+ *  communications between same or different hosts (though on same host
+ *  [NSMessagePort] will be more efficient).</p>
+ *
+ *  <p>Note that this class is incompatible with the latest OS X version.</p>
+ */
 @interface NSSocketPort : NSPort <GCFinalization>
 {
   NSRecursiveLock	*myLock;
@@ -115,23 +194,76 @@ typedef SOCKET NSSocketNativeHandle;
   NSMapTable		*handles;	/* Handles indexed by socket.	*/
 }
 
+/**
+ * Look up and return an existing <code>NSSocketPort</code> given a host and
+ * number, or return nil if one has not been created.
+ */
 + (NSSocketPort*) existingPortWithNumber: (gsu16)number
 				  onHost: (NSHost*)aHost;
+
+/**
+ * This is the preferred initialisation method for <code>NSSocketPort</code>.
+ * <br/>
+ * number should be a TCP/IP port number or may be zero for a port on
+ * the local host.<br/>
+ * aHost should be the host for the port or may be nil for the local
+ * host.<br/>
+ * addr is the IP address that MUST be used for this port - if it is nil
+ * then, for the local host, the port uses ALL IP addresses, and for a
+ * remote host, the port will use the first address that works.<br/>
+ * shouldListen specifies whether to listen on the port initially.
+ */
 + (NSSocketPort*) portWithNumber: (gsu16)number
 			  onHost: (NSHost*)aHost
 		    forceAddress: (NSString*)addr
 			listener: (BOOL)shouldListen;
 
+/**
+ *  Setup method: add new send or receive connection handle.
+ */
 - (void) addHandle: (GSTcpHandle*)handle forSend: (BOOL)send;
+
+/**
+ *  Returns IP address of underlying socket.
+ */
 - (NSString*) address;
+
+/**
+ * This is a callback method used by the NSRunLoop class to determine which
+ * descriptors to watch for the port.
+ */
 - (void) getFds: (int*)fds count: (int*)count;
+
+/**
+ *
+ */
 - (GSTcpHandle*) handleForPort: (NSSocketPort*)recvPort
 		    beforeDate: (NSDate*)when;
+
+/**
+ *  Delegates processing of a message.
+ */
 - (void) handlePortMessage: (NSPortMessage*)m;
+
+/**
+ * Returns host that the underlying socket is connected to.
+ */
 - (NSHost*) host;
+
+/**
+ *  Returns port number of underlying socket.
+ */
 - (gsu16) portNumber;
+
+/**
+ * This is called when a TCP/IP socket connection is broken.  We remove the
+ * connection handle from this port and, if this was the last handle to a
+ * remote port, we invalidate the port.
+ */
 - (void) removeHandle: (GSTcpHandle*)handle;
 
+
+// This is the OS X interface
 /*
 {
   NSSocketNativeHandle _socket;
@@ -169,6 +301,11 @@ typedef SOCKET NSSocketNativeHandle;
 
 @class GSMessageHandle;
 
+/**
+ *  An [NSPort] implementation for network object communications based on
+ *  Unix domain sockets.  Can be used for interthread/interprocess
+ *  communications on the same host, but not between different hosts.
+ */
 @interface NSMessagePort : NSPort <GCFinalization>
 {
   NSData		*name;
@@ -179,11 +316,31 @@ typedef SOCKET NSSocketNativeHandle;
 
 - (int) _listener;
 - (const unsigned char *) _name;
+
+/**
+ *  <init/>
+ * This is the preferred initialisation method for <code>NSMessagePort</code>.
+ *
+ * socketName is the name of the socket in the port directory
+ */
 + (NSMessagePort*) _portWithName: (const unsigned char *)socketName
 			listener: (BOOL)shouldListen;
 
+/**
+ *  Setup method: add new send or receive connection handle.
+ */
 - (void) addHandle: (GSMessageHandle*)handle forSend: (BOOL)send;
+
+/**
+ * This is called when a socket connection is broken.  We remove the
+ * connection handle from this port and, if this was the last handle to a
+ * remote port, we invalidate the port.
+ */
 - (void) removeHandle: (GSMessageHandle*)handle;
+
+/**
+ *  Delegates processing of a message.
+ */
 - (void) handlePortMessage: (NSPortMessage*)m;
 
 @end

Headers/Foundation/NSPortCoder.h

@@ -31,6 +31,17 @@
 @class NSConnection;
 @class NSPort;
 
+/**
+ * This class is an [NSCoder] implementation specialized for sending objects
+ * over network connections for immediate use (as opposed to the archivers
+ * which persist objects for reconstitution after an indefinite term).  It is
+ * used to help implement the distributed objects framework by the
+ * [NSConnection] class.  Even for highly specialized applications, you
+ * probably do not need to use this class directly.
+ */
+//FIXME: the above is what Apple's docs say, but looking at the code the
+// NSConnection is actually created by this class rather than the other way
+// around, so maybe the docs should be changed..
 @interface NSPortCoder : NSCoder
 {
 @private
@@ -77,18 +88,57 @@
   NSZone		*_zone;		/* Zone for allocating objs.	*/
 }
 
+/**
+ * Create a new instance for communications over send and recv, and send an
+ * initial message through send as specified by comp.
+ */
 + (NSPortCoder*) portCoderWithReceivePort: (NSPort*)recv
 				 sendPort: (NSPort*)send
 			       components: (NSArray*)comp;
+
+/**
+ * Initialize a new instance for communications over send and recv, and send an
+ * initial message through send as specified by comp.
+ */
 - (id) initWithReceivePort: (NSPort*)recv
 		  sendPort: (NSPort*)send
 		components: (NSArray*)comp;
 
+/**
+ * Returns the <code>NSConnection</code> using this instance.
+ */
 - (NSConnection*) connection;
+
+/**
+ * Return port object previously encoded by this instance.  Mainly for use
+ * by the ports themselves.
+ */
 - (NSPort*) decodePortObject;
+
+/**
+ * Processes and acts upon the initial message the receiver was initialized
+ * with..
+ */
 - (void) dispatch;
+
+/**
+ * Encodes aPort so it can be sent to the receiving side of the connection.
+ * Mainly for use by the ports themselves.
+ */
 - (void) encodePortObject: (NSPort*)aPort;
+
+/**
+ * Returns YES if receiver is in the process of encoding objects by copying
+ * them (rather than substituting a proxy).  This method is mainly needed
+ * internally and by subclasses.
+ */
 - (BOOL) isBycopy;
+
+/**
+ * Returns YES if receiver will substitute a proxy when encoding objects
+ * rather than by copying them.  This method is mainly needed
+ * internally and by subclasses.
+ */
 - (BOOL) isByref;
 
 @end

Headers/Foundation/NSPortMessage.h

@@ -27,6 +27,15 @@
 #include <Foundation/NSArray.h>
 #include <Foundation/NSPort.h>
 
+/**
+ * <p>The data transported for distributed objects communications is sent over
+ * the network encapsulated by NSPortMessage objects, which consist of two
+ * [NSPort]s (sender and receiver, not sent over the network) and a body
+ * consisting of one or more [NSData] or [NSPort] objects. (Data in the
+ * [NSData] must be in network byte order.)</p>
+ *
+ * <p>See the [NSConnection] and [NSPortCoder] classes.</p>
+ */
 @interface	NSPortMessage : NSObject
 {
   unsigned		_msgid;
@@ -34,15 +43,59 @@
   NSPort		*_send;
   NSMutableArray	*_components;
 }
+/**
+ * OpenStep compatibility.
+ */
 - (id) initWithMachMessage: (void*)buffer;
+
+/** <init/> Initializes to send message described by items (which should
+ * contain only [NSPort] and/or [NSData] objects, with contents in network
+ * byte order) over aPort.  If/when a reply to the message is sent, it will
+ * arrive on anotherPort.
+ */
 - (id) initWithSendPort: (NSPort*)aPort
 	    receivePort: (NSPort*)anotherPort
 	     components: (NSArray*)items;
+
+/**
+ * Request that the message be sent before when.  Will block until either
+ * sends it (returns YES) or when expires (returns NO).  The latter may occur
+ * if many messages are queued up (by multiple threads) faster than they can
+ * be sent over the network.
+ */
 - (BOOL) sendBeforeDate: (NSDate*)when;
+
+/**
+ * Returns the message components originally used to constitute this message.
+ */
 - (NSArray*) components;
+
+/**
+ * For an outgoing message, returns the port the receiver will send itself
+ * through.  For an incoming message, returns the port replies to the receiver
+ * should be sent through.
+ */
 - (NSPort*) sendPort;
+
+/**
+ * For an outgoing message, returns the port on which a reply to this message
+ * will arrive.  For an incoming message, returns the port this message
+ * arrived on.
+ */
 - (NSPort*) receivePort;
+
+/**
+ * Sets ID for message.  This is not used by the distributed objects system,
+ * but may be used in custom ways by cooperating applications to sort or
+ * otherwise organize messages.
+ */
 - (void) setMsgid: (unsigned)anId;
+
+/**
+ * Returns ID for message.  This is not used by the distributed objects
+ * system, but may be used in custom ways by cooperating applications to sort
+ * or otherwise organize messages.  Set to 0 initially.
+ */
 - (unsigned) msgid;
 @end
 

Headers/Foundation/NSPropertyList.h

@@ -76,12 +76,138 @@ typedef enum {
 /**
  * <p>The NSPropertyListSerialization class provides facilities for
  * serialising and deserializing property list data in a number of
- * formats.
+ * formats.  A property list is roughly an [NSArray] or [NSDictionary] object,
- * </p>
+ * with these or [NSNumber], [NSData], [NSString], or [NSDate] objects
+ * as members.  (See below.)</p>
  * <p>You do not work with instances of this class, instead you use a
- * small number of claass methods to serialized and deserialize
+ * small number of class methods to serialize and deserialize
  * property lists.
- * </p>
+ * </p><br/>
+ * A <em>property list</em> may only be one of the following classes - 
+ * <deflist>
+ *   <term>[NSArray]</term>
+ *   <desc>
+ *     An array which is either empty or contains only <em>property list</em>
+ *     objects.<br />
+ *     An array is delimited by round brackets and its contents are comma
+ *     <em>separated</em> (there is no comma after the last array element).
+ *     <example>
+ *       ( "one", "two", "three" )
+ *     </example>
+ *     In XML format, an array is an element whose name is <code>array</code>
+ *     and whose content is the array content.
+ *     <example>
+ *       &lt;array&gt;&lt;string&gt;one&lt;/string&gt;&lt;string&gt;two&lt;/string&gt;&lt;string&gt;three&lt;/string&gt;&lt;/array&gt;
+ *     </example>
+ *   </desc>
+ *   <term>[NSData]</term>
+ *   <desc>
+ *     An array is represented as a series of pairs of hexadecimal characters
+ *     (each pair representing a byte of data) enclosed in angle brackets.
+ *     Spaces are ignored).
+ *     <example>
+ *       &lt; 54637374 696D67 &gt;
+ *     </example>
+ *     In XML format, a data object is an element whose name is
+ *     <code>data</code> and whose content is a stream of base64 encoded bytes.
+ *   </desc>
+ *   <term>[NSDate]</term>
+ *   <desc>
+ *     Date objects were not traditionally allowed in <em>property lists</em>
+ *     but were added when the XML format was introduced.  GNUstep provides
+ *     an extension to the traditional <em>property list</em> format to
+ *     support date objects, but older code will not read
+ *     <em>property lists</em> containing this extension.<br />
+ *     This format consists of an asterisk follwed by the letter 'D' then a
+ *     date/time in YYYY-MM-DD HH:MM:SS +/-ZZZZ format, all enclosed within
+ *     angle brackets.
+ *     <example>
+ *       &lt;*D2002-03-22 11:30:00 +0100&gt;
+ *     </example>
+ *     In XML format, a date object is an element whose name is
+ *     <code>date</code> and whose content is a date in the above format.
+ *     <example>
+ *       &lt;date&gt;2002-03-22 11:30:00 +0100&lt;/date&gt;
+ *     </example>
+ *   </desc>
+ *   <term>[NSDictionary]</term>
+ *   <desc>
+ *     A dictionary which is either empty or contains only <em>string</em>
+ *     keys and <em>property list</em> objects.<br />
+ *     A dictionary is delimited by curly brackets and its contents are
+ *     semicolon <em>terminated</em> (there is a semicolon after each value).
+ *     Each item in the dictionary is a key/value pair with an equals sign
+ *     after the key and before the value.
+ *     <example>
+ *       {
+ *         "key1" = "value1";
+ *       }
+ *     </example>
+ *     In XML format, a dictionary is an element whose name is
+ *     <code>dictionary</code> and whose content consists of pairs of
+ *     strings and other <em>property list</em> objects.
+ *     <example>
+ *       &lt;dictionary&gt;
+ *         &lt;string&gt;key1&lt;/string&gt;
+ *         &lt;string&gt;value1&lt;/string&gt;
+ *       &lt;/dictionary&gt;
+ *     </example>
+ *   </desc>
+ *   <term>[NSNumber]</term>
+ *   <desc>
+ *     Number objects were not traditionally allowed in <em>property lists</em>
+ *     but were added when the XML format was intoroduced.  GNUstep provides
+ *     an extension to the traditional <em>property list</em> format to
+ *     support number objects, but older code will not read
+ *     <em>property lists</em> containing this extension.<br />
+ *     Numbers are stored in a variety of formats depending on their values.
+ *     <list>
+ *       <item>boolean ... either <code>&lt;*BY&gt;</code> for YES or
+ *         <code>&lt;*BN&gt;</code> for NO.<br />
+ *         In XML format this is either <code>&lt;true /&gt;</code> or
+ *         <code>&lt;false /&gt;</code>
+ *       </item>
+ *       <item>integer ... <code>&lt;*INNN&gt;</code> where NNN is an
+ *         integer.<br />
+ *         In XML format this is <code>&lt;integer&gt;NNN&lt;integer&gt;</code>
+ *       </item>
+ *       <item>real ... <code>&lt;*RNNN&gt;</code> where NNN is a real
+ *         number.<br />
+ *         In XML format this is <code>&lt;real&gt;NNN&lt;real&gt;</code>
+ *       </item>
+ *     </list>
+ *   </desc>
+ *   <term>[NSString]</term>
+ *   <desc>
+ *     A string is either stored literally (if it contains no spaces or special
+ *     characters), or is stored as a quoted string with special characters
+ *     escaped where necessary.<br />
+ *     Escape conventions are similar to those normally used in ObjectiveC
+ *     programming, using a backslash followed by -
+ *     <list>
+ *      <item><strong>\</strong> a backslash character</item>
+ *      <item><strong>"</strong> a quote character</item>
+ *      <item><strong>b</strong> a backspace character</item>
+ *      <item><strong>n</strong> a newline character</item>
+ *      <item><strong>r</strong> a carriage return character</item>
+ *      <item><strong>t</strong> a tab character</item>
+ *      <item><strong>OOO</strong> (three octal digits)
+ *	  an arbitrary ascii character</item>
+ *      <item><strong>UXXXX</strong> (where X is a hexadecimal digit)
+ *	  a an arbitrary unicode character</item>
+ *     </list>
+ *     <example>
+ *       "hello world &amp; others"
+ *     </example>
+ *     In XML format, the string is simply stored in UTF8 format as the
+ *     content of a <code>string</code> element, and the only character
+ *     escapes  required are those used by XML such as the
+ *     '&amp;lt;' markup representing a '&lt;' character.
+ *     <example>
+ *       &lt;string&gt;hello world &amp;amp; others&lt;/string&gt;"
+ *     </example>
+ *   </desc>
+ * </deflist>
  */
 @interface NSPropertyListSerialization : NSObject
 {
@@ -108,7 +234,7 @@ typedef enum {
  * Deserialises dataItem and returns the resulting property list
  * (or nil if the data does not contain a property list serialised
  * in a supported format).<br />
- * The argument anOption is ised to control whether the objects making
+ * The argument anOption is used to control whether the objects making
  * up the deserialized property list are mutable or not.<br />
  * The argument aFormat is either null or a pointer to a location
  * in which the format of the serialized property list will be returned.<br />

Headers/Foundation/NSRange.h

@@ -47,6 +47,11 @@
 #endif
 
 /**
+ * <example>
+{
+  unsigned int location;
+  unsigned int length;
+}</example>
  * <p>
  *   The NSRange type is used to specify ranges of locations,
  *   typically items in an array, characters in a string, and bytes

Headers/Foundation/NSRunLoop.h

@@ -130,7 +130,7 @@ typedef	enum {
  * These are general purpose methods for letting objects ask
  * the runloop to watch for events for them.  Only one object
  * at a time may be watching for a particular event in a mode, but
- * that object may add itsself as a watcher many times as long as
+ * that object may add itself as a watcher many times as long as
  * each addition is matched by a removal (the run loop keeps count).
  * Alternatively, the 'removeAll' parameter may be set to 'YES' for
  * [-removeEvent:type:forMode:all:] in order to remove the watcher
@@ -165,9 +165,13 @@ typedef	enum {
 		 all: (BOOL)removeAll;
 @end
 
-/* xxx This interface will probably change. */
+/**
+ * Defines implementation-helper method -getFds:count:.
+ * <strong>This interface will probably change.  Do not rely on it.</strong>
+ */
+// xxx This interface will probably change.
 @interface NSObject (OptionalPortRunLoop)
-/* If a InPort object responds to this, it is sent just before we are
+/** If a InPort object responds to this, it is sent just before we are
    about to wait listening for input.
    This interface will probably change. */
 - (void) getFds: (int*)fds count: (int*)count;

Headers/Foundation/NSSerialization.h

@@ -30,24 +30,61 @@
 
 @class NSData, NSMutableData;
 
+/**
+ *  Objects that are not standard property list constituents can adopt this
+ *  protocol to allow themselves to be serialized by an [NSSerializer] and
+ *  deserialized by an [NSDeserializer].  <em>Note, this mechanism has been
+ *  deprecated and you should instead use [NSArchiver] and related facilities
+ *  to serialize objects that are not ordinary property lists.</em>
+ */
 @protocol NSObjCTypeSerializationCallBack
+
+/**
+ *  Decodes an object of given type from data at position cursor.
+ */
 - (void) deserializeObjectAt: (id*)object
 		  ofObjCType: (const char *)type
 		    fromData: (NSData*)data
 		    atCursor: (unsigned*)cursor;
+
+/**
+ *  Encode the given object of given type into data, using a string not a
+ *  binary representation.
+ */
 - (void) serializeObjectAt: (id*)object
 		ofObjCType: (const char *)type
 		  intoData: (NSMutableData*)data;
 @end
 
+/**
+ *  <p><em>This class is deprecated in favor of
+ *  [NSPropertyListSerialization].</em></p>
+ *
+ *  <p>It provides a means of producing a byte-array (actually string)
+ *  representation of a property list (NSArray or NSDictionary plus limited
+ *  contents).</p>
+ */
 @interface NSSerializer: NSObject
+
+/**
+ *  <p>Serialize given property list (NSArray or NSDictionary plus limited
+ *  contents) into byte array.</p>  <p><em>Deprecated in favor of
+ *  [NSPropertyListSerialization+dataFromPropertyList:format:errorDescription:].</em></p>
+ */
 + (NSData*) serializePropertyList: (id)propertyList;
+
+/**
+ *  <p>Serialize given property list (NSArray or NSDictionary plus limited
+ *  contents) into given mutable byte array.</p>  <p><em>Deprecated in favor of
+ *  [NSPropertyListSerialization+dataFromPropertyList:format:errorDescription:].</em></p>
+
+ */
 + (void) serializePropertyList: (id)propertyList
 		      intoData: (NSMutableData*)d;
 @end
 
 #ifndef	NO_GNUSTEP
-/*
+/**
  *	GNUstep extends serialization by having the option to make the
  *	resulting data more compact by ensuring that repeated strings
  *	are only stored once.  If the property-list has a lot of repeated
@@ -60,19 +97,56 @@
  *	override the default behavior.
  */
 @interface NSSerializer (GNUstep)
+
+/**
+ *  Specify whether to produce compacted format, with repeated strings only
+ *  written once.
+ */
 + (void) shouldBeCompact: (BOOL)flag;
+
+/**
+ *  As [NSSerializer+serializePropertyList:intoData:] but specify whether to
+ *  produce compacted format.
+ */
 + (void) serializePropertyList: (id)propertyList
 		      intoData: (NSMutableData*)d
 		       compact: (BOOL)flag;
 @end
 #endif
 
+/**
+ *  <em>This class is deprecated in favor of
+ *  [NSPropertyListSerialization].</em> It provides a means of recovering a
+ *  property list (NSArray or NSDictionary plus limited contents) from a
+ *  byte-array (actually string) representation.
+ */
 @interface NSDeserializer: NSObject
+
+/**
+ *  Recover a property list (NSArray or NSDictionary plus limited
+ *  contents) from a byte array.  <em>Deprecated in favor of
+ *  [NSPropertyListSerialization+propertyListFromData:mutabilityOption:format:errorDescription:].</em>
+ */
 + (id) deserializePropertyListFromData: (NSData*)data
 			      atCursor: (unsigned int*)cursor
 		     mutableContainers: (BOOL)flag;
+
+/**
+ *  Recover a property list (NSArray or NSDictionary plus limited
+ *  contents) from a byte array.  <em>Deprecated in favor of
+ *  [NSPropertyListSerialization+propertyListFromData:mutabilityOption:format:errorDescription:].</em>
+ */
 + (id) deserializePropertyListFromData: (NSData*)data
 		     mutableContainers: (BOOL)flag;
+
+/**
+ *  Recover a property list (NSArray or NSDictionary plus limited contents)
+ *  from a byte array.  If the data at cursor has a length greater than
+ *  length, a proxy is substituted for the actual property list as long as the
+ *  constituent objects of that property list are not accessed.
+ *  <em>Deprecated in favor of
+ *  [NSPropertyListSerialization+propertyListFromData:mutabilityOption:format:errorDescription:].</em>
+ */
 + (id) deserializePropertyListLazilyFromData: (NSData*)data
 				    atCursor: (unsigned*)cursor
 				      length: (unsigned)length
@@ -81,21 +155,24 @@
 @end
 
 #ifndef	NO_GNUSTEP
-/*
+/**
- *	GNUstep extends deserialization by having the option to make the
+ *	<p>GNUstep extends deserialization by having the option to make the
  *	resulting data more compact by ensuring that repeated strings
  *	are only stored once.  If the property-list has a lot of repeated
  *	strings in it, this will be more space efficient but it will be
  *	slower (though other parts of your code may speed up through more
  *	efficient equality testing of uniqued strings).
- *	The default is NOT to deserialize uniqued strings.
+ *	The default is NOT to deserialize uniqued strings.</p>
  *
- *	The [+uniquing:] method turns uniquing on/off.
+ *	<p>The [+uniquing:] method turns uniquing on/off.
- *	Uniquing is done using a global NSCountedSet - see NSCountedSet for
+ *	Uniquing is done using a global [NSCountedSet] - see its documentation
- *	details.
+ *	for details.</p>
  */
-@class	NSMutableSet;
 @interface NSDeserializer (GNUstep)
+/**
+ * Turns uniquing (collapsing of multiple instances of a single string in the
+ * output to one full copy plus references) on/off.
+ */
 + (void) uniquing: (BOOL)flag;
 @end
 

Headers/Foundation/NSSet.h

@@ -98,39 +98,77 @@
 
 #ifndef NO_GNUSTEP
 
-/*
+/**
  * Utility methods for using a counted set to handle uniquing of objects.
  */
 @interface NSCountedSet (GNU_Uniquing)
+/**
+ * <p>
+ *   This method removes from the set all objects whose count is
+ *   less than or equal to the specified value.
+ * </p>
+ * <p>
+ *   This is useful where a counted set is used for uniquing objects.
+ *   The set can be periodically purged of objects that have only
+ *   been added once - and are therefore simply wasting space.
+ * </p>
+ */
 - (void) purge: (int)level;
+
+/**
+ * <p>
+ *   If the supplied object (or one equal to it as determined by
+ *   the [-isEqual:] method) is already present in the set, the
+ *   count for that object is incremented, the supplied object
+ *   is released, and the object in the set is retained and returned.
+ *   Otherwise, the supplied object is added to the set and returned.
+ * </p>
+ * <p> 
+ *   This method is useful for uniquing objects - the init method of
+ *   a class need simply end with -
+ *   <code>
+ *     return [myUniquingSet unique: self];
+ *   </code>
+ * </p>
+ */
 - (id) unique: (id)anObject;
 @end
 
 /*
  * Functions for managing a global uniquing set.
- *
+ */
+
+/*
  * GSUniquing() turns on/off the action of the GSUnique() function.
  * if uniquing is turned off, GSUnique() simply returns its argument.
  *
+ */
+void	GSUniquing(BOOL flag);	
+
+/*
  * GSUnique() returns an object that is equal to the one passed to it.
  * If the returned object is not the same object as the object passed in,
  * the original object is released and the returned object is retained.
  * Thus, an -init method that wants to implement uniquing simply needs
  * to end with 'return GSUnique(self);'
  */
-void	GSUniquing(BOOL flag);	
 id	GSUnique(id anObject);
 
 /*
  * Management functions -
- *
+ */
+
+/*
  * GSUPurge() can be used to purge infrequently referenced objects from the
  * set by removing any objec whose count is less than or equal to that given.
  *
+ */
+void	GSUPurge(unsigned count);
+
+/*
  * GSUSet() can be used to artificially set the count for a particular object
  * Setting the count to zero will remove the object from the global set.
  */
-void	GSUPurge(unsigned count);
 id	GSUSet(id anObject, unsigned count);
 
 #endif /* NO_GNUSTEP */

Headers/Foundation/NSString.h

@@ -349,10 +349,10 @@ enum {
  * added for GNUstep, to permit the isa variable to be set to another
  * class, and GNUstep uses this to avoid conflicts with the default
  * implementation of NXConstantString in the ObjC runtime library (the
- * preprocessor is used to change all occurances of NXConstantString
+ * preprocessor is used to change all occurences of NXConstantString
  * in the source code to NSConstantString).</p>
  * <p>Since GNUstep will generally use the GNUstep extension to the
- * compiler, you should never refer to the constnat string class by
+ * compiler, you should never refer to the constant string class by
  * name, but should use the [NSString+constantStringClass] method to
  * get the actual class being used for constant strings.</p>
  * What follows is a dummy declaration of the class to keep the compiler
@@ -377,25 +377,101 @@ extern struct objc_class _NSConstantStringClassReference;
 - (NSString*) immutableProxy;
 @end
 
+/**
+ * Provides some additional (non-standard) utility methods.
+ */
 @interface NSString (GSCategories)
+/**
+ * Alternate way to invoke <code>stringWithFormat</code> if you have or wish
+ * to build an explicit <code>va_list</code> structure.
+ */
 + (id) stringWithFormat: (NSString*)format
 	      arguments: (va_list)argList;
+
+/**
+ * Returns a string formed by removing the prefix string from the
+ * receiver.  Raises an exception if the prefix is not present.
+ */
 - (NSString*) stringByDeletingPrefix: (NSString*)prefix;
+
+/**
+ * Returns a string formed by removing the suffix string from the
+ * receiver.  Raises an exception if the suffix is not present.
+ */
 - (NSString*) stringByDeletingSuffix: (NSString*)suffix;
+
+/**
+ * Returns a string formed by removing leading white space from the
+ * receiver.
+ */
 - (NSString*) stringByTrimmingLeadSpaces;
+
+/**
+ * Returns a string formed by removing trailing white space from the
+ * receiver.
+ */
 - (NSString*) stringByTrimmingTailSpaces;
+
+/**
+ * Returns a string formed by removing both leading and trailing
+ * white space from the receiver.
+ */
 - (NSString*) stringByTrimmingSpaces;
+
+/**
+ * Returns a string in which any (and all) occurrences of
+ * replace in the receiver have been replaced with by.
+ * Returns the receiver if replace
+ * does not occur within the receiver.  NB. an empty string is
+ * not considered to exist within the receiver.
+ */
 - (NSString*) stringByReplacingString: (NSString*)replace
 			   withString: (NSString*)by;
 @end
 
+
+/**
+ * GNUstep specific (non-standard) additions to the NSMutableString class.
+ */
 @interface NSMutableString (GSCategories)
+
+/**
+ * Removes the specified suffix from the string.  Raises an exception
+ * if the suffix is not present.
+ */
 - (void) deleteSuffix: (NSString*)suffix;
+
+/**
+ * Removes the specified prefix from the string.  Raises an exception
+ * if the prefix is not present.
+ */
 - (void) deletePrefix: (NSString*)prefix;
+
+/**
+ * Replaces all occurrances of the string replace with the string by
+ * in the receiver.<br />
+ * Has no effect if replace does not occur within the
+ * receiver.  NB. an empty string is not considered to exist within
+ * the receiver.<br />
+ * Calls - replaceOccurrencesOfString:withString:options:range: passing
+ * zero for the options and a range from 0 with the length of the receiver.
+ */
 - (void) replaceString: (NSString*)replace
 	    withString: (NSString*)by;
+
+/**
+ * Removes all leading white space from the receiver.
+ */
 - (void) trimLeadSpaces;
+
+/**
+ * Removes all trailing white space from the receiver.
+ */
 - (void) trimTailSpaces;
+
+/**
+ * Removes all leading or trailing white space from the receiver.
+ */
 - (void) trimSpaces;
 @end
 

Headers/Foundation/NSURL.h

@@ -82,12 +82,27 @@ GS_EXPORT NSString* NSURLFileScheme;
 @end
 
 @interface NSObject (NSURLClient)
+
+/**
+ * Some data has become available.  Note that this does not mean that all data
+ * has become available, only that a chunk of data has arrived.
+ */
 - (void) URL: (NSURL*)sender
   resourceDataDidBecomeAvailable: (NSData*)newBytes;
 
+/**
+ * Loading of resource data is complete.
+ */
 - (void) URLResourceDidFinishLoading: (NSURL*)sender;
+
+/**
+ * Loading of resource data was canceled by programmatic request (not an error).
+ */
 - (void) URLResourceDidCancelLoading: (NSURL*)sender;
 
+/**
+ * Loading of resource data has failed, for given human-readable reason.
+ */
 - (void) URL: (NSURL*)sender
   resourceDidFailLoadingWithReason: (NSString*)reason;
 @end

Headers/Foundation/NSURLHandle.h

@@ -58,7 +58,7 @@ typedef enum
 
 /**
  * A protocol to which clients of a handle must conform in order to
- * rfeceive notification of events on the handle.
+ * receive notification of events on the handle.
  */
 @protocol NSURLHandleClient
 /**

Headers/Foundation/NSValue.h

@@ -29,105 +29,315 @@
 
 @class NSString;
 
+/**
+ * The <code>NSValue</code> class can wrap a single primitive value as an
+ * object so it can be used in the containers and other places where an object
+ * reference is needed. Once initialized, an <code>NSValue</code> is
+ * immutable, and there is no <code>NSMutableValue</code> class. You
+ * initialize it by giving it a pointer to the primitive value, and you should
+ * be careful this does not get freed until after the <code>NSValue</code> is
+ * no longer used.
+ */
 @interface NSValue : NSObject <NSCopying, NSCoding>
 
 // Allocating and Initializing 
 
+/**
+ * Create new instance with specified value (a pointer) of given type, which
+ * is a string code obtainable through the compile-time operator
+ * <code>@encode(...)</code>.  For example:
+<example>
+    NSValue *theValue = [NSValue value: &amp;n withObjCType: @encode(int)];
+</example>
+ */
 + (NSValue*) value: (const void*)value withObjCType: (const char*)type;
+
+/**
+ * Create new instance holding anObject.  This is useful if you want to add
+ * anObject to a collection such as [NSArray] but don't want it to be retained
+ * (a weak reference).
+ */
 + (NSValue*) valueWithNonretainedObject: (id)anObject;
+
+/**
+ * Convenience method to create instance holding an <code>NSPoint</code>
+ * structure.
+ */
 + (NSValue*) valueWithPoint: (NSPoint)point;
+
+/**
+ * Convenience method to create instance holding a pointer.  Same as
+ * using <code>@encode(void *)</code> in +value:withObjCType: .
+ */
 + (NSValue*) valueWithPointer: (const void*)pointer;
+
+/**
+ * Convenience method to create instance holding an <code>NSRange</code>
+ * structure.
+ */
 + (NSValue*) valueWithRange: (NSRange)range;
+
+/**
+ * Convenience method to create instance holding an <code>NSRect</code>
+ * structure.
+ */
 + (NSValue*) valueWithRect: (NSRect)rect;
+
+/**
+ * Convenience method to create instance holding an <code>NSSize</code>
+ * structure.
+ */
 + (NSValue*) valueWithSize: (NSSize)size;
 
 #ifndef STRICT_OPENSTEP
+/**
+ * Synonym for value:withObjCType: .
+ */
 + (NSValue*) valueWithBytes: (const void*)value objCType: (const char*)type;
-/* Designated initializer for all concrete subclasses */
+
+/** <init/>
+ * Initialize with value of type, parallel to value:withObjCType: .
+ */
 - (id) initWithBytes: (const void*)data objCType: (const char*)type;
+
+/**
+ * Compares this instance to another <code>NSValue</code>.  For equality,
+ * both contents and declared type of the two values must match.
+ */
 - (BOOL) isEqualToValue: (NSValue*)other;
 #endif
 
 // Accessing Data 
 
+/**
+ * Copies bytes from the pointer receiver was initialized with into buffer
+ * pointed to by value.  Number of bytes copied is determined by the type.  If
+ * type was a void * pointer or object id, the memory address itself is
+ * copied.
+ */
 - (void) getValue: (void*)value;
+
+/**
+ * Returns the string <code>@encode(...)</code> compatible type the receiver
+ * was initialized with.
+ */
 - (const char*) objCType;
+
+/**
+ * If receiver was initialized with an object ID, return it, else raises
+ * <code>NSInternalInconsistencyException</code>.
+ */
 - (id) nonretainedObjectValue;
+
+/**
+ * If receiver was initialized with a void * pointer, return it, else raises
+ * <code>NSInternalInconsistencyException</code>.
+ */
 - (void*) pointerValue;
+
+/**
+ * If receiver was initialized with an <code>NSRange</code> value, return it,
+ * else raises <code>NSInternalInconsistencyException</code>.
+ */
 - (NSRange) rangeValue;
+
+/**
+ * If receiver was initialized with an <code>NSRect</code> value, return it,
+ * else raises <code>NSInternalInconsistencyException</code>.
+ */
 - (NSRect) rectValue;
+
+/**
+ * If receiver was initialized with an <code>NSSize</code> value, return it,
+ * else raises <code>NSInternalInconsistencyException</code>.
+ */
 - (NSSize) sizeValue;
+
+/**
+ * If receiver was initialized with an <code>NSPoint</code> value, return it,
+ * else raises <code>NSInternalInconsistencyException</code>.
+ */
 - (NSPoint) pointValue;
 
 @end
 
+/**
+ * Subclass of [NSValue] offering convenience methods for initializing from
+ * and accessing as any C primitive numeric type.  On access, the value will
+ * be type-converted if necessary, using standard C conversion rules.
+ */
 @interface NSNumber : NSValue <NSCopying,NSCoding>
 
 // Allocating and Initializing
 
+/** New instance from boolean value. */
 + (NSNumber*) numberWithBool: (BOOL)value; 
+/** New instance from signed char value. */
 + (NSNumber*) numberWithChar: (signed char)value;
+/** New instance from double value. */
 + (NSNumber*) numberWithDouble: (double)value;
+/** New instance from float value. */
 + (NSNumber*) numberWithFloat: (float)value;
+/** New instance from (signed) int value. */
 + (NSNumber*) numberWithInt: (signed int)value;
+/** New instance from (signed) long value. */
 + (NSNumber*) numberWithLong: (signed long)value;
+/** New instance from (signed) long long value. */
 + (NSNumber*) numberWithLongLong: (signed long long)value;
+/** New instance from (signed) short value. */
 + (NSNumber*) numberWithShort: (signed short)value;
+/** New instance from unsigned char value. */
 + (NSNumber*) numberWithUnsignedChar: (unsigned char)value;
+/** New instance from unsigned int value. */
 + (NSNumber*) numberWithUnsignedInt: (unsigned int)value;
+/** New instance from unsigned long value. */
 + (NSNumber*) numberWithUnsignedLong: (unsigned long)value;
+/** New instance from unsigned long long value. */
 + (NSNumber*) numberWithUnsignedLongLong: (unsigned long long)value;
+/** New instance from unsigned short value. */
 + (NSNumber*) numberWithUnsignedShort: (unsigned short)value;
 
+/** Initialize from boolean value. */
 - (id) initWithBool: (BOOL)value;
+/** Initialize from signed char value. */
 - (id) initWithChar: (signed char)value;
+/** Initialize from double value. */
 - (id) initWithDouble: (double)value;
+/** Initialize from float value. */
 - (id) initWithFloat: (float)value;
+/** Initialize from (signed) int value. */
 - (id) initWithInt: (signed int)value;
+/** Initialize from (signed) long value. */
 - (id) initWithLong: (signed long)value;
+/** Initialize from (signed) long long value. */
 - (id) initWithLongLong: (signed long long)value;
+/** Initialize from (signed) short value. */
 - (id) initWithShort: (signed short)value;
+/** Initialize from unsigned char value. */
 - (id) initWithUnsignedChar: (unsigned char)value;
+/** Initialize from unsigned int value. */
 - (id) initWithUnsignedInt: (unsigned int)value;
+/** Initialize from unsigned long value. */
 - (id) initWithUnsignedLong: (unsigned long)value;
+/** Initialize from unsigned long long value. */
 - (id) initWithUnsignedLongLong: (unsigned long long)value;
+/** Initialize from unsigned short value. */
 - (id) initWithUnsignedShort: (unsigned short)value;
 
 // Accessing Data 
 
+/**
+ * Return value as a BOOL; this will in fact be a char value converted
+ * if necessary from type initialized with; if you wish to consider anything
+ * nonzero TRUE do not compare directly to YES, but use <code>'!= NO'</code>.
+ */
 - (BOOL) boolValue;
+/** Returns value as a signed char, converting if necessary. */
 - (signed char) charValue;
+/** Returns value as a double, converting if necessary. */
 - (double) doubleValue;
+/** Returns value as a float, converting if necessary. */
 - (float) floatValue;
+/** Returns value as a (signed) int, converting if necessary. */
 - (signed int) intValue;
-- (signed long long) longLongValue;
+/** Returns value as a (signed) long, converting if necessary. */
 - (signed long) longValue;
+/** Returns value as a (signed) long long, converting if necessary. */
+- (signed long long) longLongValue;
+/** Returns value as a (signed) short, converting if necessary. */
 - (signed short) shortValue;
-- (NSString*) stringValue;
+/** Returns value as an unsigned char, converting if necessary. */
 - (unsigned char) unsignedCharValue;
+/** Returns value as an unsigned int, converting if necessary. */
 - (unsigned int) unsignedIntValue;
-- (unsigned long long) unsignedLongLongValue;
+/** Returns value as an unsigned long, converting if necessary. */
 - (unsigned long) unsignedLongValue;
+/** Returns value as an unsigned long long, converting if necessary. */
+- (unsigned long long) unsignedLongLongValue;
+/** Returns value as an unsigned short, converting if necessary. */
 - (unsigned short) unsignedShortValue;
 
+/** Returns -description . */
+- (NSString*) stringValue;
+
+/**
+ * Returns the string representation of this number using a non-localised
+ * conversion (decimal point is '.' irrespective of the locale).
+ */
 - (NSString*) description;
+
+/**
+ * <p>
+ *   Produces a string representation of the number.  For a boolean
+ *   this will be either 'true' or 'false'.  For other numbers the
+ *   format is produced using the initWithFormat:locale:... method
+ *   of NSString, and the format depends on the type of number as
+ *   follows -
+ * </p>
+ * <deflist>
+ *   <term>char</term>
+ *   <desc>%i</desc>
+ *   <term> short</term>
+ *   <desc>%hi</desc>
+ *   <term> int</term>
+ *   <desc>%i</desc>
+ *   <term> long</term>
+ *   <desc>%li</desc>
+ *   <term> long long</term>
+ *   <desc>%lli</desc>
+ *   <term> unsigned char</term>
+ *   <desc>%u</desc>
+ *   <term> unsigned short</term>
+ *   <desc>%hu</desc>
+ *   <term> unsigned int</term>
+ *   <desc>%u</desc>
+ *   <term> unsigned long</term>
+ *   <desc>%lu</desc>
+ *   <term> unsigned long long</term>
+ *   <desc>%llu</desc>
+ *   <term> float</term>
+ *   <desc>%0.7g</desc>
+ *   <term> double</term>
+ *   <desc>%0.16g</desc>
+ * </deflist>
+ */
 - (NSString*) descriptionWithLocale: (NSDictionary*)locale;
 
+/**
+ * Compares receiver with otherNumber, using C type conversion if necessary,
+ * and returns <code>NSOrderedAscending</code>,
+ * <code>NSOrderedDescending</code>, or <code>NSOrderedSame</code> depending
+ * on whether it is less than, greater than, or equal to otherNumber.
+ */
 - (NSComparisonResult) compare: (NSNumber*)otherNumber;
+
+/**
+ * Returns whether receiver and otherNumber represent the same numerical value.
+ */
 - (BOOL) isEqualToNumber: (NSNumber*)otherNumber;
 @end
 
 #ifndef	NO_GNUSTEP
 
+/**
+ * GNUstep specific (non-standard) additions to the NSNumber class.
+ */
 @interface NSNumber(GSCategories)
+
+/**
+ * Parses string as a <code>double</code>, <code>int</code>, or <code>unsigned
+ * int</code> depending on what characters are present.  Uses
+ * <code>atof</code> and <code>atoi</code> which don't report errors, so be
+ * careful if the string might contain an invalid value.
+ */
 + (NSValue*) valueFromString: (NSString *)string;
 @end
 
-/* Note: This method is not in the OpenStep spec, but they makes
+/** Note: Defines a method that is not in the OpenStep spec, but makes
-   subclassing easier. */
+    subclassing easier. */
 @interface NSValue (Subclassing)
 
-/* Used by value: withObjCType: to determine the concrete subclass to alloc */
+/** Used by value: withObjCType: to determine the concrete subclass to alloc. */
 + (Class) valueClassWithObjCType: (const char*)type;
 
 @end