From 6c28122b3bb8c46b5f4ebbd8f43ca875bb81466c Mon Sep 17 00:00:00 2001
From: CaS <CaS@72102866-910b-0410-8b05-ffd578937521>
Date: Tue, 31 Dec 2002 10:41:10 +0000
Subject: [PATCH] Documentation improvements.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@15422 72102866-910b-0410-8b05-ffd578937521
---
 ChangeLog                          |  3 ++
 Headers/gnustep/base/NSException.h | 61 ++++++++++++++++++++++++++++--
 Source/NSAssertionHandler.m        | 19 ++++++++++
 Source/NSException.m               |  2 +-
 4 files changed, 81 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 673ac0704..04f632a67 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -8,6 +8,9 @@
 	* Source/NSHashTable.m: Update for macosx compatibility, add some
 	documentation and move stuff from externs.m
 	* Source/externs.m: Remove map and hash table stuff
+	* Source/NSException.m: Fix documentation cross ref error.
+	* Source/NSAssertion.m: Improve documentation.
+	* Headers/gnustep/base/NSException.h: Include assertion documentation.
 	* Headers/gnustep/base/NSMapTable.h: Update for macosx compatibility.
 	* Headers/gnustep/base/NSHashTable.h: Ditto
 	* Tools/AGSHtml.m: Fix typo ... excess semicolon in constant output.
diff --git a/Headers/gnustep/base/NSException.h b/Headers/gnustep/base/NSException.h
index 64e9bac85..46277a246 100644
--- a/Headers/gnustep/base/NSException.h
+++ b/Headers/gnustep/base/NSException.h
@@ -1,4 +1,4 @@
-/* Interface for NSException for GNUStep
+/** Interface for NSException for GNUStep
    Copyright (C) 1995, 1996 Free Software Foundation, Inc.
 
    Written by:  Adam Fedor <fedor@boulder.colorado.edu>
@@ -19,6 +19,10 @@
    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
+
+    AutogsdocSource: NSAssertionHandler.m
+    AutogsdocSource: NSException.m
+
    */ 
 
 #ifndef __NSException_h_GNUSTEP_BASE_INCLUDE
@@ -178,47 +182,98 @@ GS_EXPORT void _NSRemoveHandler( NSHandler *handler );
     } while(0)
 #endif
 
-/* Asserts to use in Objective-C method bodies*/ 
+/** Used in an ObjC method body.<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2,
+ * arg3, arg4, arg5 */
 #define NSAssert5(condition, desc, arg1, arg2, arg3, arg4, arg5)	\
     _NSAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4), (arg5))
 
+/** Used in an ObjC method body.<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2,
+ * arg3, arg4 */
 #define NSAssert4(condition, desc, arg1, arg2, arg3, arg4)	\
     _NSAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4))
 
+/** Used in an ObjC method body.<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2,
+ * arg3 */
 #define NSAssert3(condition, desc, arg1, arg2, arg3)	\
     _NSAssertArgs((condition), (desc), (arg1), (arg2), (arg3))
 
+/** Used in an ObjC method body.<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2 */
 #define NSAssert2(condition, desc, arg1, arg2)		\
     _NSAssertArgs((condition), (desc), (arg1), (arg2))
 
+/** Used in an ObjC method body.<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc  and arg1 */
 #define NSAssert1(condition, desc, arg1)		\
     _NSAssertArgs((condition), (desc), (arg1))
 
+/** Used in an ObjC method body.<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc */
 #define NSAssert(condition, desc)			\
     _NSAssertArgs((condition), (desc))
 
+/** Used in an ObjC method body.<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception saying that an invalid
+ * parameter was supplied to the method. */
 #define NSParameterAssert(condition)			\
     _NSAssertArgs((condition), @"Invalid parameter not satisfying: %s", #condition)
 
-/* Asserts to use in C function bodies */
+/** Used in plain C code (not in an ObjC method body).<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2,
+ * arg3, arg4, arg5 */
 #define NSCAssert5(condition, desc, arg1, arg2, arg3, arg4, arg5)	\
     _NSCAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4), (arg5))
 
+/** Used in plain C code (not in an ObjC method body).<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2,
+ * arg3, arg4 */
 #define NSCAssert4(condition, desc, arg1, arg2, arg3, arg4)	\
     _NSCAssertArgs((condition), (desc), (arg1), (arg2), (arg3), (arg4))
 
+/** Used in plain C code (not in an ObjC method body).<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2,
+ * arg3 */
 #define NSCAssert3(condition, desc, arg1, arg2, arg3)	\
     _NSCAssertArgs((condition), (desc), (arg1), (arg2), (arg3))
 
+/** Used in plain C code (not in an ObjC method body).<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1, arg2
+ */
 #define NSCAssert2(condition, desc, arg1, arg2)		\
     _NSCAssertArgs((condition), (desc), (arg1), (arg2))
 
+/** Used in plain C code (not in an ObjC method body).<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc and arg1
+ */
 #define NSCAssert1(condition, desc, arg1)		\
     _NSCAssertArgs((condition), (desc), (arg1))
 
+/** Used in plain C code (not in an ObjC method body).<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception using desc
+ */
 #define NSCAssert(condition, desc)			\
     _NSCAssertArgs((condition), (desc))
 
+/** Used in plain C code (not in an ObjC method body).<br />
+ * See [NSAssertionHandler] for details.<br />
+ * When condition is false, raise an exception saying that an invalid
+ * parameter was supplied to the method. */
 #define NSCParameterAssert(condition)			\
     _NSCAssertArgs((condition), @"Invalid parameter not satisfying: %s", #condition)
 
diff --git a/Source/NSAssertionHandler.m b/Source/NSAssertionHandler.m
index 83a894cd4..7b065f950 100644
--- a/Source/NSAssertionHandler.m
+++ b/Source/NSAssertionHandler.m
@@ -32,6 +32,25 @@
 #include <Foundation/NSString.h>
 #include <Foundation/NSThread.h>
 
+/**
+ * <p>NSAssertionHandler objects are used to raise exceptions on behalf of
+ * macros implementing assertions.<br />
+ * Each thread has its own assertion handler instance.<br />
+ * </p>
+ * <p>The macros work together with the assertion handler object to
+ * produce meaningful exception messages containing the name of the
+ * source file, the position within that file, and the name of the
+ * ObjC method or C function in which the assertion failed.
+ * </p>
+ * The assertion macros are:
+ * NSAssert(), NSCAssert(),
+ * NSAssert1(), NSCAssert1(),
+ * NSAssert2(), NSCAssert2(),
+ * NSAssert3(), NSCAssert3(),
+ * NSAssert4(), NSCAssert4(),
+ * NSAssert5(), NSCAssert5(),
+ * NSParameterAssert(), NSCParameterAssert()
+ */
 @implementation NSAssertionHandler
 
 /* Key for thread dictionary. */
diff --git a/Source/NSException.m b/Source/NSException.m
index 98fc101c9..05a1872a5 100644
--- a/Source/NSException.m
+++ b/Source/NSException.m
@@ -144,7 +144,7 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
    <p>
    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 exeption is using the +raise:format:
+   The easiest way to cause an exeption is using the +raise:format:,...
    method.
    </p>
 */