Complete documentation.

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

Source/NSThread.m

@@ -250,6 +250,17 @@ gnustep_base_thread_callback()
 }
 
 
+/**
+ * This class encapsulates OpenStep threading.  See [NSLock] and its
+ * subclasses for handling synchronisation between threads.<br />
+ * Each process begins with a main thread and additional threads can
+ * be created using NSThread.  The GNUstep implementation of OpenStep
+ * has been carefully designed so that the internals of the base
+ * library do not use threading (except for methods which explicitly
+ * deal with threads of course) so that you can write applications
+ * without threading.  Non-threaded applications re more efficient
+ * (no locking is required) and are easier to debug during development.
+ */
 @implementation NSThread
 
 /**
@@ -796,6 +807,13 @@ static NSDate *theFuture;
 }
 @end
 
+/**
+ * Extra methods to permit messages to be sent to an object such that they
+ * are executed in the <em>main</em> thread.<br />
+ * The main thread is the thread in which the GNUstep system is started,
+ * and where the GNUstep gui is used, it is the thread in which gui
+ * drawing operations <strong>must</strong> be performed.
+ */
 @implementation	NSObject (NSMainThreadPerformAdditions)
 
 /**
@@ -807,9 +825,10 @@ static NSDate *theFuture;
  * runs in one of the modes specified in anArray.<br />
  * Where this method has been called more than once before the runloop
  * of the main thread runs in the required mode, the order in which the
- * 'perform' operations in the main thread is done is the same as that
- * in which they were added.<br />
- * If there are no modes in anArray,
+ * operations in the main thread is done is the same as that in which
+ * they were added using this method.
+ * </p>
+ * <p>If there are no modes in anArray,
  * the method has no effect and simply returns immediately.
  * </p>
  * <p>The argument aFlag specifies whether the method should wait until
@@ -820,7 +839,7 @@ static NSDate *theFuture;
  * will block forever.
  * </p>
  * <p>As a special case, if aFlag == YES and the current thread is the main
- * thread, the modes array is ignord and the selector is performed immediately.
+ * thread, the modes array is ignored and the selector is performed immediately.
  * This behavior is necessary to avoid the main thread being blocked by
  * waiting for a perform which will never happen because the runloop is
  * not executing.