Documentation.

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

ChangeLog

@@ -1,3 +1,9 @@
+2002-10-26  Adam Fedor  <fedor@gnu.org>
+
+	* Source/NSException.m: Document.
+	* Source/NSFileHandle.m: Partial Documentation.
+	* Source/NSObject.m: Fix typo in docs.
+
 2002-10-25  Mirko Viviani  <mirko.viviani@rccr.cremona.it>
 
 	* Source/NSBundle.m ([NSBundle -load]): set _codeLoaded before loading

Source/NSException.m

@@ -119,8 +119,43 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
     }
 }
 
+/**
+   <p>
+   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.
+   </p>
+   <p>
+   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:
+   </p>
+   <example>
+   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
+   </example>
+   <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:
+   method.
+   </p>
+*/
 @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
@@ -129,6 +164,11 @@ _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,...
 {
@@ -136,10 +176,15 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
 
   va_start(args, format);
   [self raise: name format: format arguments: args];
-  // FIXME: This probably doesn't matter, but va_end won't get called
+  // This probably doesn't matter, but va_end won't get called
   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
@@ -152,6 +197,10 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
   [except raise];
 }
 
+/**
+   <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
@@ -170,6 +219,13 @@ _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, or to the uncaught exception handler if there is no
+   other handling code.
+*/
 - (void) raise
 {
   NSThread	*thread;
@@ -193,6 +249,7 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
   longjmp(handler->jumpState, 1);
 }
 
+/** Returns the name of the exception */
 - (NSString*) name
 {
   if (_e_name != nil)
@@ -205,6 +262,7 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
     }
 }
 
+/** Returns the exception reason */
 - (NSString*) reason
 {
   if (_e_reason != nil)
@@ -217,6 +275,7 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception)
     }
 }
 
+/** Returns the exception userInfo dictionary */
 - (NSDictionary*) userInfo
 {
   return _e_info;

Source/NSFileHandle.m

@@ -50,6 +50,19 @@ static Class NSFileHandle_abstract_class = nil;
 static Class NSFileHandle_concrete_class = nil;
 static Class NSFileHandle_ssl_class = nil;
 
+/**
+ * <p>
+ * NSFileHandler is a Class that provides a wrapper for accessing
+ * system files and other connections. You can open connections to a
+ * file using class methods such as +fileHandleForReadingAtPath:.
+ * </p>
+ * <p>
+ * GNUstep extends the use of this Class to allow you to create
+ * network connections (sockets), secure connections and also allows
+ * you to use compression with these files and connections (as long as
+ * GNUstep Base was compiled with the zlib library).
+ * </p>
+ */
 @implementation NSFileHandle
 
 + (void) initialize
@@ -74,7 +87,11 @@ static Class NSFileHandle_ssl_class = nil;
 }
 
 // Allocating and Initializing a FileHandle Object
-
+/** 
+ * Returns an NSFileHandle object setup for reading from the
+ * file listed at path. If the file does not exist or cannot
+ * be opened for some other reason, nil is returned.
+ */
 + (id) fileHandleForReadingAtPath: (NSString*)path
 {
   id	o = [self allocWithZone: NSDefaultMallocZone()];
@@ -82,6 +99,11 @@ static Class NSFileHandle_ssl_class = nil;
   return AUTORELEASE([o initForReadingAtPath: path]);
 }
 
+/** 
+ * Returns an NSFileHandle object setup for writing to the
+ * file listed at path. If the file does not exist or cannot
+ * be opened for some other reason, nil is returned.
+ */
 + (id) fileHandleForWritingAtPath: (NSString*)path
 {
   id	o = [self allocWithZone: NSDefaultMallocZone()];
@@ -89,6 +111,11 @@ static Class NSFileHandle_ssl_class = nil;
   return AUTORELEASE([o initForWritingAtPath: path]);
 }
 
+/** 
+ * Returns an NSFileHandle object setup for updating (reading and
+ * writing) from the file listed at path. If the file does not exist
+ * or cannot be opened for some other reason, nil is returned.
+ */
 + (id) fileHandleForUpdatingAtPath: (NSString*)path
 {
   id	o = [self allocWithZone: NSDefaultMallocZone()];
@@ -96,6 +123,11 @@ static Class NSFileHandle_ssl_class = nil;
   return AUTORELEASE([o initForUpdatingAtPath: path]);
 }
 
+/** 
+ * Returns an NSFileHandle object for the standard error descriptor.
+ * The returned object is a shared instance as there can only be one
+ * standard error per process.
+ */
 + (id) fileHandleWithStandardError
 {
   id	o = [self allocWithZone: NSDefaultMallocZone()];
@@ -103,6 +135,11 @@ static Class NSFileHandle_ssl_class = nil;
   return AUTORELEASE([o initWithStandardError]);
 }
 
+/** 
+ * Returns an NSFileHandle object for the standard input descriptor.
+ * The returned object is a shared instance as there can only be one
+ * standard input per process.
+ */
 + (id) fileHandleWithStandardInput
 {
   id	o = [self allocWithZone: NSDefaultMallocZone()];
@@ -110,6 +147,11 @@ static Class NSFileHandle_ssl_class = nil;
   return AUTORELEASE([o initWithStandardInput]);
 }
 
+/** 
+ * Returns an NSFileHandle object for the standard output descriptor.
+ * The returned object is a shared instance as there can only be one
+ * standard output per process.
+ */
 + (id) fileHandleWithStandardOutput
 {
   id	o = [self allocWithZone: NSDefaultMallocZone()];
@@ -117,6 +159,13 @@ static Class NSFileHandle_ssl_class = nil;
   return AUTORELEASE([o initWithStandardOutput]);
 }
 
+/** 
+ * Returns a file handle object that is connected to the null device
+ * (i.e. a device that does nothing.)  It is typically used in arrays
+ * and other collections of file handle objects as a place holder
+ * (null) object, so that all objects can respond to the same
+ * messages.
+ */
 + (id) fileHandleWithNullDevice
 {
   id	o = [self allocWithZone: NSDefaultMallocZone()];
@@ -210,7 +259,10 @@ static Class NSFileHandle_ssl_class = nil;
 
 /**
  * Set up an asynchonous read operation which will cause a notification to
- * be sent when any amount of data (or end of file) is read.
+ * be sent when any amount of data (or end of file) is read. Note that
+ * the file handle will not continuously send notifications when data
+ * is available. If you want to continue to receive notifications, you
+ * need to send this message again after receiving a notification.
  */
 - (void) readInBackgroundAndNotifyForModes: (NSArray*)modes
 {

Source/NSObject.m

@@ -1942,11 +1942,9 @@ static BOOL double_release_check_enabled = NO;
  * for debugging.
  * </p>
  * <p>
- * Where you are having memory allocation problems, it may make more sense
- * to look at the memory allocation debugging functions documnented in
- *  look at the memory allocation debugging functions documnented in
- * NSDebug.h, or use the NSZombie features.NSDebug.h, or use the NSZombie
- * features.  
+ * When you are having memory allocation problems, it may make more sense
+ * to look at the memory allocation debugging functions documented in
+ * NSDebug.h, or use the NSZombie features.
  * </p>
  */
 + (void) enableDoubleReleaseCheck: (BOOL)enable