From 3d41142bdf4fa917edeea7d3f77ebf76a7b715b7 Mon Sep 17 00:00:00 2001 From: arobert Date: Mon, 2 Aug 2004 18:10:58 +0000 Subject: [PATCH] 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 | 11 ++++++----- Headers/Foundation/NSDecimal.h | 7 ++++--- Headers/Foundation/NSException.h | 24 +++++++++++++++++++----- Headers/Foundation/NSFileHandle.h | 4 ++-- Headers/Foundation/NSGeometry.h | 2 +- Headers/Foundation/NSRange.h | 4 ++-- Headers/Foundation/NSRunLoop.h | 3 ++- Headers/Foundation/NSThread.h | 9 ++++++--- Headers/Foundation/NSUndoManager.h | 5 +++-- Headers/Foundation/NSUserDefaults.h | 12 ++++++------ 10 files changed, 51 insertions(+), 30 deletions(-) diff --git a/Headers/Foundation/NSBundle.h b/Headers/Foundation/NSBundle.h index eb52f0fdb..ab1f1fe78 100644 --- a/Headers/Foundation/NSBundle.h +++ b/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 NSShowNonLocalizedStrings is set. If set, the +

Returns the value for the key found in the strings file tableName, or + Localizable.strings if tableName is nil.

+ +

If the user default NSShowNonLocalizedStrings 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".

*/ - (NSString*) localizedStringForKey: (NSString*)key value: (NSString*)value diff --git a/Headers/Foundation/NSDecimal.h b/Headers/Foundation/NSDecimal.h index d3b02bd1b..2be9a40a6 100644 --- a/Headers/Foundation/NSDecimal.h +++ b/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); diff --git a/Headers/Foundation/NSException.h b/Headers/Foundation/NSException.h index 404736022..b890ba7ae 100644 --- a/Headers/Foundation/NSException.h +++ b/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 NS_DURING and - * NS_HANDLER...NS_ENDHANDLER). It prints an error - * message and exits the program. You can change this behavior by calling - * NSSetUncaughtExceptionHandler(fn_ptr). + * 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 NS_DURING and + * NS_HANDLER...NS_ENDHANDLER). 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 NS_DURING and + * NS_HANDLER...NS_ENDHANDLER). The default prints + * an error message and exits the program. proc should take a single argument + * of type NSException *. + */ #define NSSetUncaughtExceptionHandler(proc) \ (_NSUncaughtExceptionHandler = (proc)) diff --git a/Headers/Foundation/NSFileHandle.h b/Headers/Foundation/NSFileHandle.h index 867349639..f6ff1865e 100644 --- a/Headers/Foundation/NSFileHandle.h +++ b/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; diff --git a/Headers/Foundation/NSGeometry.h b/Headers/Foundation/NSGeometry.h index 44d7c0f16..e8d8d7423 100644 --- a/Headers/Foundation/NSGeometry.h +++ b/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 diff --git a/Headers/Foundation/NSRange.h b/Headers/Foundation/NSRange.h index c03b7ae3a..fb25ec789 100644 --- a/Headers/Foundation/NSRange.h +++ b/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 diff --git a/Headers/Foundation/NSRunLoop.h b/Headers/Foundation/NSRunLoop.h index d88b0ddeb..033473be4 100644 --- a/Headers/Foundation/NSRunLoop.h +++ b/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. { ET_RDESC, // Watch for descriptor becoming readable. diff --git a/Headers/Foundation/NSThread.h b/Headers/Foundation/NSThread.h index 9221d3c41..daff4e59b 100644 --- a/Headers/Foundation/NSThread.h +++ b/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 not + * 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 may 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; diff --git a/Headers/Foundation/NSUndoManager.h b/Headers/Foundation/NSUndoManager.h index 819cc29c4..3d02ed987 100644 --- a/Headers/Foundation/NSUndoManager.h +++ b/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 userInfo dictionary. + * Notification posted whenever [NSUndoManager] opens or closes an undo + * group. The undo manager itself is the notification object, with no + * userInfo dictionary. */ GS_EXPORT NSString *NSUndoManagerCheckpointNotification; diff --git a/Headers/Foundation/NSUserDefaults.h b/Headers/Foundation/NSUserDefaults.h index 42c88b9cf..d58fddf37 100644 --- a/Headers/Foundation/NSUserDefaults.h +++ b/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