From 32c69565d9305fb4d9aa49c511a84e6ec04a1c12 Mon Sep 17 00:00:00 2001 From: CaS Date: Thu, 1 Dec 2005 19:51:45 +0000 Subject: [PATCH] Improve NSException documentation a little git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@22128 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 4 +- Headers/Foundation/NSException.h | 135 +++++++++++++++++++++++++++++-- Source/NSException.m | 89 -------------------- 3 files changed, 131 insertions(+), 97 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3a4f26858..8c8daa3fc 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,7 +1,9 @@ 2005-12-01 Richard Frith-Macdonald - * Source/NSpathUtilities.m: Add more checks/warnings about improper + * Source/NSPathUtilities.m: Add more checks/warnings about improper configuration. + * Headers/Foundation/NSException.h: clarify/extend documentation. + * Source/NSException.m: move some documentation to header. 2005-11-28 Richard Frith-Macdonald diff --git a/Headers/Foundation/NSException.h b/Headers/Foundation/NSException.h index cd8a9e459..56d643891 100644 --- a/Headers/Foundation/NSException.h +++ b/Headers/Foundation/NSException.h @@ -36,6 +36,45 @@ @class NSDictionary; +/** +

+ The NSException class helps manage errors in a program. It + provides a mechanism for lower-level methods to provide information about + problems to higher-level methods, which more often than not, have a + better ability to decide what to do about the problems. +

+

+ Exceptions are typically handled by enclosing a sensitive section + of code inside the macros NS_DURING and NS_HANDLER, + and then handling any problems after this, up to the + NS_ENDHANDLER macro: +

+ + NS_DURING + code that might cause an exception + NS_HANDLER + code that deals with the exception. If this code cannot deal with + it, you can re-raise the exception like this + [localException raise] + so the next higher level of code can handle it + NS_ENDHANDLER + +

+ The local variable localException is the name of the exception + object you can use in the NS_HANDLER section. + The easiest way to cause an exception is using the +raise:format:,... + method. +

+

+ If there is no NS_HANDLER ... NS_ENDHANDLER block enclosing (directly or + indirectly) code where an exception is raised, then control passes to + the uncaught exception handler function and the program is + then terminated.
+ The uncaught exception handler is set using NSSetUncaughtExceptionHandler() + and if not set, defaults to a function which will simply print an error + message before the program terminates. +

+*/ @interface NSException : NSObject { NSString *_e_name; @@ -43,40 +82,108 @@ NSDictionary *_e_info; } +/** + Create an an exception object with a name, reason and a dictionary + userInfo which can be used to provide additional information or + access to objects needed to handle the exception. After the + exception is created you must -raise it. +*/ + (NSException*) exceptionWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo; + +/** + Creates an exception with a name and a reason using the + format string and any additional arguments. The exception is then + raised using the -raise method. + */ + (void) raise: (NSString*)name format: (NSString*)format,...; + +/** + Creates an exception with a name and a reason string using the + format string and additional arguments specified as a variable + argument list argList. The exception is then raised + using the -raise method. + */ + (void) raise: (NSString*)name format: (NSString*)format arguments: (va_list)argList; +/** + Initializes a newly allocated NSException object with a + name, reason and a dictionary userInfo. +*/ - (id) initWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo; + +/** Returns the name of the exception. */ +- (NSString*) name; + +/** + Raises the exception. All code following the raise will not be + executed and program control will be transfered to the closest + calling method which encapsulates the exception code in an + NS_DURING macro.
+ If the exception was not caught in a macro, the currently set + uncaught exception handler is called to perform final logging + and the program is then terminated.
+ If the uncaught exception handler fails to terminate the program, + then the default behavior is to terminate the program as soon as + the uncaught exception handler function returns.
+ NB. all other exception raising methods call this one, so if you + want to set a breakpoint when debugging, set it in this method. +*/ - (void) raise; -// Querying Exceptions -- (NSString*) name; +/** Returns the exception reason. */ - (NSString*) reason; + +/** Returns the exception userInfo dictionary. */ - (NSDictionary*) userInfo; @end -/* Common exceptions */ +/** + * A generic exception for general purpose usage. + */ GS_EXPORT NSString* const NSGenericException; + +/** + * An exception for cases where unexpected state is detected within an object. + */ GS_EXPORT NSString* const NSInternalInconsistencyException; + +/** + * An exception used when an invalid argument is passed to a method + * or function. + */ GS_EXPORT NSString* const NSInvalidArgumentException; + +/** + * An exception used when the system fails to allocate required memory. + */ GS_EXPORT NSString* const NSMallocException; + +/** + * An exception used when an illegal range is encountered ... usually this + * is used to provide more information than an invalid argument exception. + */ GS_EXPORT NSString* const NSRangeException; + +/** + * An exception when character set conversion fails. + */ GS_EXPORT NSString* const NSCharacterConversionException; + #ifndef STRICT_OPENSTEP +/** + * An exception used when some form of parsing fails. + */ GS_EXPORT NSString* const NSParseErrorException; #endif -/* Exception handler definitions */ - /** * The actual structure for an NSHandler. You shouldn't need to worry about it. */ @@ -96,7 +203,7 @@ typedef void NSUncaughtExceptionHandler(NSException *exception); /** * Variable used to hold the current uncaught exception handler. Use the - * function NSSetUncaughtExceptionHandler() to set. + * function NSSetUncaughtExceptionHandler() to set this. */ GS_EXPORT NSUncaughtExceptionHandler *_NSUncaughtExceptionHandler; @@ -110,11 +217,25 @@ GS_EXPORT NSUncaughtExceptionHandler *_NSUncaughtExceptionHandler; #define NSGetUncaughtExceptionHandler() _NSUncaughtExceptionHandler /** - * Sets the exception handler called when an exception is generated and + *

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 *. + *

+ *

NB. If the exception handler set by this function does not terminate + * the process, the process will be terminateed anyway. This is a safety + * precaution to ensure that, in the event of an exception ebing raised + * and not handled, the program does not try to continue running in a + * confused state (possibly doing horrible things like billing customers + * who shouldn't be billed etc), but shuts down as cleanly as possible. + *

+ *

Process termination is normally accomplished by calling the standard + * exit function of theC runtime library, but if the environment variable + * CRASH_ON_ABORT is set to YES or TRUE or 1 the termination will be + * accomplished by calling the abort function instead, which should cause + * a core dump to be made for debugging. + *

*/ #define NSSetUncaughtExceptionHandler(proc) \ (_NSUncaughtExceptionHandler = (proc)) diff --git a/Source/NSException.m b/Source/NSException.m index 6d83c734f..8dfd32305 100644 --- a/Source/NSException.m +++ b/Source/NSException.m @@ -33,47 +33,24 @@ #include "Foundation/NSDictionary.h" #include -/** - * A generic exception for general purpose usage. - */ NSString* const NSGenericException = @"NSGenericException"; -/** - * An exception for cases where unexpected state is detected within an object. - */ NSString* const NSInternalInconsistencyException = @"NSInternalInconsistencyException"; -/** - * An exception used when an invalid argument is passed to a method - * or function. - */ NSString* const NSInvalidArgumentException = @"NSInvalidArgumentException"; -/** - * An exception used when the system fails to allocate required memory. - */ NSString* const NSMallocException = @"NSMallocException"; -/** - * An exception used when an illegal range is encountered ... usually this - * is used to provide more information than an invalid argument exception. - */ NSString* const NSRangeException = @"NSRangeException"; -/** - * An exception when character set conversion fails. - */ NSString* const NSCharacterConversionException = @"NSCharacterConversionException"; -/** - * An exception used when some form of parsing fails. - */ NSString* const NSParseErrorException = @"NSParseErrorException"; @@ -111,44 +88,8 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) _terminate(); } -/** -

- The NSException class helps manage errors in a program. It - provides a mechanism for lower-level methods to provide information about - problems to higher-level methods, which more often than not, have a - better ability to decide what to do about the problems. -

-

- Exceptions are typically handled by enclosing a sensitive section - of code inside the macros NS_DURING and NS_HANDLER, - and then handling any problems after this, up to the - NS_ENDHANDLER macro: -

- - NS_DURING - code that might cause an exception - NS_HANDLER - code that deals with the exception. If this code cannot deal with - it, you can re-raise the exception like this - [localException raise] - so the next higher level of code can handle it - NS_ENDHANDLER - -

- The local variable localException is the name of the exception - object you can use in the NS_HANDLER section. - The easiest way to cause an exception is using the +raise:format:,... - method. -

-*/ @implementation NSException -/** - Create an an exception object with a name, reason and a dictionary - userInfo which can be used to provide additional information or - access to objects needed to handle the exception. After the - exception is created you must -raise it. -*/ + (NSException*) exceptionWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo @@ -157,11 +98,6 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) userInfo: userInfo]); } -/** - Creates an exception with a name and a reason using the - format string and any additional arguments. The exception is then - raised. - */ + (void) raise: (NSString*)name format: (NSString*)format,... { @@ -173,11 +109,6 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) va_end(args); } -/** - Creates an exception with a name and a reason string using the - format string and additional arguments specified as a variable - argument list argList. The exception is then raised. - */ + (void) raise: (NSString*)name format: (NSString*)format arguments: (va_list)argList @@ -190,10 +121,6 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) [except raise]; } -/** - Initializes a newly allocated NSException object with a - name, reason and a dictionary userInfo. -*/ - (id) initWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo @@ -212,19 +139,6 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) [super dealloc]; } -/** - Raises the exception. All code following the raise will not be - executed and program control will be transfered to the closest - calling method which encapsulates the exception code in an - NS_DURING macro.
- If the exception was not caught in a macro, the currently set - uncaught exception handler is called to perform final logging - and handle program termination.
- If the uncaught exception handler fails to terminate the program, - then the default builtin uncaught exception handler will do so.
- NB. all other exception raising methods call this one, so if you - want to set a breakpoint when debugging, set it in this method. -*/ - (void) raise { NSThread *thread; @@ -273,7 +187,6 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) longjmp(handler->jumpState, 1); } -/** Returns the name of the exception. */ - (NSString*) name { if (_e_name != nil) @@ -286,7 +199,6 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) } } -/** Returns the exception reason. */ - (NSString*) reason { if (_e_reason != nil) @@ -299,7 +211,6 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) } } -/** Returns the exception userInfo dictionary. */ - (NSDictionary*) userInfo { return _e_info;