stack trace fixups

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

ChangeLog

@@ -1,3 +1,10 @@
+2007-02-06  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Documentation/manual/manual.texi: fix format errors
+	* Source/NSException.m: control stack trace with environment variable
+	* Headers/Foundation/NSException.h: document stack trace
+	* Documentation/Base.gsdoc: document stack trace
+
 2007-02-05  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* configure.ac: minor tweak to avoid possible inconsistency in

Documentation/Base.gsdoc

@@ -269,6 +269,16 @@ notice and this notice are preserved.
 		core dump on systems where that is possible.
 	      </p>
 	    </desc>
+	    <term>GNUSTEP_STACK_TRACE</term>
+	    <desc>
+	      <p>
+	        When this is set to <em>YES</em> a stack trace is placed in
+		the user information dictionary of the NSException object
+		created when an exception is raised.  The trace is keyed
+		on <code>GSStackTraceKey</code> and provides additional
+		information to let you know where the exception occurred.
+	      </p>
+	    </desc>
 	    <term>GNUSTEP_STRING_ENCODING</term>
 	    <desc>
 	      <p>

Documentation/manual/manual.texi

@@ -95,16 +95,16 @@ into another language, under the above conditions for modified versions.
 @page
 
 @c Chapter 1, Introduction
-@include Introduction.texi 
+@include Introduction.texi
 
 @c Chapter 2, The Objective-C Language
-@include ObjcLanguage.texi 
+@include ObjcLanguage.texi
 
 @c Chapter 3, Working with Objects
-@include WorkingWithObjects.texi 
+@include WorkingWithObjects.texi
 
 @c Chapter 4, Writing New Classes
-@include WritingNewClasses.texi 
+@include WritingNewClasses.texi
 
 @c Chapter 5, Advanced Messaging
 @include AdvancedMessaging.texi

Headers/Foundation/NSException.h

@@ -89,37 +89,37 @@ extern "C" {
 }
 
 /**
-   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.
-*/
+ * 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
-   <em>raised</em> using the -raise method.
+ * Creates an exception with a name and a reason using the
+ * format string and any additional arguments. The exception is then
+ * <em>raised</em> 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 <em>raised</em>
-   using the -raise method.
+ * 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 <em>raised</em>
+ * using the -raise method.
  */
 + (void) raise: (NSString*)name
 	format: (NSString*)format
      arguments: (va_list)argList;
 
 /**
-   <init/>Initializes a newly allocated NSException object with a
-   name, reason and a dictionary userInfo.
-*/
+ * <init/>Initializes a newly allocated NSException object with a
+ * name, reason and a dictionary userInfo.
+ */
 - (id) initWithName: (NSString*)name 
 	     reason: (NSString*)reason 
 	   userInfo: (NSDictionary*)userInfo;
@@ -128,25 +128,31 @@ extern "C" {
 - (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.<br />
-   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.<br />
-   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.<br />
-   NB. all other exception raising methods call this one, so if you
-   want to set a breakpoint when debugging, set it in this method.
-*/
+ * 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.<br />
+ * 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.<br />
+ * 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.<br />
+ * 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;
 
 /** Returns the exception reason. */
 - (NSString*) reason;
 
-/** Returns the exception userInfo dictionary. */
+/** Returns the exception userInfo dictionary.<br />
+ * There is a GNUstep extension, enabled when the GNUSTEP_STACK_TRACE
+ * environment variable is set to YES, which causes a stack trace to
+ * be placed in this dictionary (keyed on GSStackTraceKey) at the point
+ * when the exception is raised.  This can be useful for determining
+ * where an exception ocurred.
+ */
 - (NSDictionary*) userInfo;
 
 @end

Source/NSException.m

@@ -681,7 +681,8 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
 #endif
 
 #if	defined(DEBUG)
-  if ([_e_info objectForKey: @"GSStackTraceKey"] == nil)
+  if (GSPrivateEnvironmentFlag("GNUSTEP_STACK_TRACE", NO) == YES
+    && [_e_info objectForKey: @"GSStackTraceKey"] == nil)
     {
       NSMutableDictionary	*m;