some cleanups and clarifications to documentation just added, suggested by Alexander Malmberg

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

Headers/Foundation/NSBundle.h

@@ -246,12 +246,13 @@ GS_EXPORT NSString* NSLoadedClasses;
 		       ofType: (NSString*)ext;
 
 /**
-   Returns the value for the key found in the strings file tableName, or
-   Localizable.strings if tableName is nil.  Behavior depends on whether the
-   user default <code>NSShowNonLocalizedStrings</code> is set.  If set, the
+   <p>Returns the value for the key found in the strings file tableName, or
+   Localizable.strings if tableName is nil.</p>
+
+   <p>If the user default <code>NSShowNonLocalizedStrings</code> is set, the
    value of the key will be returned as an uppercase string rather than any
-   localized equivalent found.  This can be useful during development to
-   check where a given string in the UI is "coming from".
+   localized equivalent found.  This can be useful during development to check
+   where a given string in the UI is "coming from".</p>
  */
 - (NSString*) localizedStringForKey: (NSString*)key
 			      value: (NSString*)value

Headers/Foundation/NSDecimal.h

@@ -111,7 +111,8 @@ typedef struct {
 #endif
 } NSDecimal;
 
-/** Returns whether decimal represents an invalid number. */
+/** Returns whether decimal represents an invalid number (i.e., an "NaN" as
+    might result from an overflow or a division by zero). */
 static inline BOOL
 NSDecimalIsNotANumber(const NSDecimal *decimal)
 {
@@ -144,7 +145,7 @@ GS_EXPORT void
 NSDecimalRound(NSDecimal *result, const NSDecimal *number, int scale, NSRoundingMode mode);
 
 /**
- *  Sets the exponents of n1 and n2 to equal one another, adjusting mantissas
+ *  Sets the exponents of n1 and n2 equal to one another, adjusting mantissas
  *  as necessary to preserve values.  This makes certain operations quicker.
  */
 GS_EXPORT NSCalculationError
@@ -199,7 +200,7 @@ NSDecimalPower(NSDecimal *result, const NSDecimal *n, unsigned power, NSRounding
  *  Multiplies n by 10^power and returns result to 38-digit precision.  See the
  *  [(NSDecimalNumberBehaviors)] protocol for a description of mode and the
  *  return value.  The result should be preallocated but can be the same as
- *  n or power.
+ *  n.
  */
 GS_EXPORT NSCalculationError
 NSDecimalMultiplyByPowerOf10(NSDecimal *result, const NSDecimal *n, short power, NSRoundingMode mode);

Headers/Foundation/NSException.h

@@ -88,11 +88,9 @@ typedef struct _NSHandler
 } NSHandler;
 
 /**
- *  This is the exception handler called when an exception is generated and
- *  not caught by the programmer (by enclosing in <code>NS_DURING</code> and
- *  <code>NS_HANDLER</code>...<code>NS_ENDHANDLER</code>).  It prints an error
- *  message and exits the program.  You can change this behavior by calling
- *  <code>NSSetUncaughtExceptionHandler(fn_ptr)</code>.
+ *  This is the type of the exception handler called when an exception is
+ *  generated and not caught by the programmer.  See
+ *  NSGetUncaughtExceptionHandler(), NSSetUncaughtExceptionHandler().
  */
 typedef void NSUncaughtExceptionHandler(NSException *exception);
 
@@ -101,7 +99,23 @@ typedef void NSUncaughtExceptionHandler(NSException *exception);
  *  function NSSetUncaughtExceptionHandler() to set.
  */
 GS_EXPORT NSUncaughtExceptionHandler *_NSUncaughtExceptionHandler;
+
+/**
+ *  Returns the exception handler called when an exception is generated and
+ *  not caught by the programmer (by enclosing in <code>NS_DURING</code> and
+ *  <code>NS_HANDLER</code>...<code>NS_ENDHANDLER</code>).  The default prints
+ *  an error message and exits the program.  You can change this behavior by
+ *  calling NSSetUncaughtExceptionHandler().
+ */
 #define NSGetUncaughtExceptionHandler() _NSUncaughtExceptionHandler
+
+/**
+ *  Sets the exception handler called when an exception is generated and
+ *  not caught by the programmer (by enclosing in <code>NS_DURING</code> and
+ *  <code>NS_HANDLER</code>...<code>NS_ENDHANDLER</code>).  The default prints
+ *  an error message and exits the program.  proc should take a single argument
+ *  of type <code>NSException *</code>.
+ */
 #define NSSetUncaughtExceptionHandler(proc) \
 			(_NSUncaughtExceptionHandler = (proc))
 

Headers/Foundation/NSFileHandle.h

@@ -123,8 +123,8 @@ GS_EXPORT NSString * const NSFileHandleReadToEndOfFileCompletionNotification;
 // Keys for accessing userInfo dictionary in notification handlers.
 
 /**
- * Dictionary key for [NSFileHandle] notifications used to mark the
- * [NSFileHandle] receiving data.
+ * Dictionary key for [NSFileHandle] notifications used to access an
+ * [NSDataItem] containing received data.
  */
 GS_EXPORT NSString * const NSFileHandleNotificationDataItem;
 

Headers/Foundation/NSGeometry.h

@@ -374,7 +374,7 @@ NSUnionRect(NSRect aRect, NSRect bRect)
 GS_GEOM_SCOPE NSRect
 NSIntersectionRect(NSRect aRect, NSRect bRect) GS_GEOM_ATTR;
 
-/** Returns the largest rectange which lies in both aRect and
+/** Returns the largest rectangle which lies in both aRect and
  * bRect.  If aRect and bRect have empty intersection (or, rather,
  * intersection of measure zero, since this includes having their
  * intersection be only a point or a line), then the empty

Headers/Foundation/NSRange.h

@@ -207,8 +207,8 @@ NSIntersectionRange (NSRange aRange, NSRange bRange)
 /** Returns string of form {location=a, length=b}. */
 GS_EXPORT NSString *NSStringFromRange(NSRange range);
 
-/** Parses range from string of form {location=a, length=b}, otherwise returns
-    range with 0 location and length if this fails. */
+/** Parses range from string of form {location=a, length=b}; returns range
+    with 0 location and length if this fails. */
 GS_EXPORT NSRange NSRangeFromString(NSString *aString);
 
 #ifdef	GS_DEFINED_MAX

Headers/Foundation/NSRunLoop.h

@@ -95,8 +95,9 @@ GS_EXPORT NSString * const NSDefaultRunLoopMode;
  */
 
 /**
- * GNUstep extension: enumeration of event types that an [NSRunLoop] watcher
+ * Enumeration of event types that an [NSRunLoop] watcher
  * can watch for.  See [NSRunLoop-addEvent:type:watcher:forMode:].
+ * This is a GNUstep extension.
  <example>
 {
     ET_RDESC,	// Watch for descriptor becoming readable.

Headers/Foundation/NSThread.h

@@ -113,8 +113,10 @@ GS_EXPORT void GSUnregisterCurrentThread (void);
 /**
  *  Notification posted the first time a new [NSThread] is created or a
  *  separate thread from another library is registered in an application.
- *  Before such a notification has been posted you can assume the application
- *  is in single-threaded mode and locks are not necessary.
+ *  (The initial thread that a program starts with does <em>not</em>
+ *  post this notification.)  Before such a notification has been posted you
+ *  can assume the application is in single-threaded mode and locks are not
+ *  necessary.  Afterwards multiple threads <em>may</em> be running.
  */
 GS_EXPORT NSString	*NSWillBecomeMultiThreadedNotification;
 #define	NSBecomingMultiThreaded NSWillBecomeMultiThreadedNotification
@@ -129,7 +131,8 @@ GS_EXPORT NSString	*NSThreadWillExitNotification;
 #ifndef	NO_GNUSTEP
 
 /**
- *  Notification posted (only in GNUstep) whenever a new thread is started up.
+ *  Notification posted whenever a new thread is started up.  This is a
+ *  GNUstep extension.
  */
 GS_EXPORT NSString	*NSThreadDidStartNotification;
 

Headers/Foundation/NSUndoManager.h

@@ -38,8 +38,9 @@ enum {
 /* Public notification */
 
 /**
- *  Notification posted whenever [NSUndoManager] opens or closes an undo group.
- *  The undo manager itself is posted, with no <em>userInfo</em> dictionary.
+ *  Notification posted whenever [NSUndoManager] opens or closes an undo
+ *  group.  The undo manager itself is the notification object, with no
+ *  <em>userInfo</em> dictionary.
  */
 GS_EXPORT NSString *NSUndoManagerCheckpointNotification;
 

Headers/Foundation/NSUserDefaults.h

@@ -120,9 +120,9 @@ GS_EXPORT NSString* const NSAMPMDesignation;
 #ifndef	STRICT_OPENSTEP
 
 /**
- *  Array of arrays, first member of specifying a time, next members one or
- *  more colloquial names for the time, as in "(0, midnight), (12, noon,
- *  lunch)".
+ *  Array of arrays of NSStrings, first member of each specifying a time,
+ *  followed by one or more colloquial names for the time, as in "(0,
+ *  midnight), (12, noon, lunch)".
  */
 GS_EXPORT NSString* const NSHourNameDesignations;
 
@@ -173,9 +173,9 @@ GS_EXPORT NSString* const NSLocale;
 
 /* General implementation notes: 
 
-   OpenStep spec currently is either complete nor consistent. Therefore
-   we had to take several implementation decisions which may vary in
-   different OpenStep implementations.
+   OpenStep spec currently is neither complete nor consistent. Therefore
+   we had to make several implementation decisions which may vary in
+   other OpenStep implementations.
   
   - We add a new instance method initWithFile:  as a designated 
     initialization method because it allows to create user defaults