diff --git a/ChangeLog b/ChangeLog
index 3bd6efafd..ad16c8f61 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2006-11-01  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/NSSortDescriptor.m; minor tidyups
+	* Headers/Foundation/NSSortDescriptor.h: add documentation
+	* Headers/Foundation/NSKeyValueCoding.h: improve version macros
+	* Headers/Foundation/NSKeyValueObserving.h: add include for NSArray
+
 2006-10-31  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/NSSocketPortNameServer.m:
diff --git a/Headers/Foundation/NSKeyValueCoding.h b/Headers/Foundation/NSKeyValueCoding.h
index 8161c3ccd..5f0b9c23d 100644
--- a/Headers/Foundation/NSKeyValueCoding.h
+++ b/Headers/Foundation/NSKeyValueCoding.h
@@ -27,6 +27,8 @@
 #define __NSKeyValueCoding_h_GNUSTEP_BASE_INCLUDE
 #import	<GNUstepBase/GSVersionMacros.h>
 
+#if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
+
 #import	<Foundation/NSObject.h>
 
 #if	defined(__cplusplus)
@@ -39,8 +41,6 @@ extern "C" {
 @class NSError;
 @class NSString;
 
-#if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
-
 /** An exception for an unknown key in [NSObject(NSKeyValueCoding)]. */
 GS_EXPORT NSString* const NSUndefinedKeyException;
 
@@ -358,11 +358,11 @@ GS_EXPORT NSString* const NSUndefinedKeyException;
 
 @end
 
-#endif
-
 #if	defined(__cplusplus)
 }
 #endif
 
+#endif	/* GS_API_MACOSX */
+
 #endif
 
diff --git a/Headers/Foundation/NSKeyValueObserving.h b/Headers/Foundation/NSKeyValueObserving.h
index 438db5810..050e949b5 100644
--- a/Headers/Foundation/NSKeyValueObserving.h
+++ b/Headers/Foundation/NSKeyValueObserving.h
@@ -26,15 +26,15 @@
 #define __NSKeyValueObserving_h_GNUSTEP_BASE_INCLUDE
 #import	<GNUstepBase/GSVersionMacros.h>
 
+#if OS_API_VERSION(100300,GS_API_LATEST) && GS_API_VERSION(010200,GS_API_LATEST)
+
 #import	<Foundation/NSObject.h>
+#import	<Foundation/NSArray.h>
 
 #if	defined(__cplusplus)
 extern "C" {
 #endif
 
-#if OS_API_VERSION(100300,GS_API_LATEST) && GS_API_VERSION(010200,GS_API_LATEST)
-
-@class NSArray;
 @class NSIndexSet;
 @class NSSet;
 @class NSString;
@@ -225,11 +225,11 @@ triggerChangeNotificationsForDependentKey: (NSString*)dependentKey;
 
 @end
 
-#endif
-
 #if	defined(__cplusplus)
 }
 #endif
 
-#endif /* __NSKeyValueObserving_h_GNUSTEP_BASE_INCLUDE */
+#endif	/* 100300 */
+
+#endif	/* __NSKeyValueObserving_h_GNUSTEP_BASE_INCLUDE */
 
diff --git a/Headers/Foundation/NSSortDescriptor.h b/Headers/Foundation/NSSortDescriptor.h
index c89091413..fdd6ee147 100644
--- a/Headers/Foundation/NSSortDescriptor.h
+++ b/Headers/Foundation/NSSortDescriptor.h
@@ -37,6 +37,11 @@ extern "C" {
 
 @class NSString;
 
+/**
+ * Instances of this class are used to perform multi-level sorts of
+ * arrays containging collections or other objects whose properties
+ * can be obtained using key names.
+ */
 @interface NSSortDescriptor : NSObject <NSCopying, NSCoding>
 {
   NSString *_key;
@@ -44,20 +49,53 @@ extern "C" {
   SEL	_selector;
 }
 
+/** Returns a flag indicating whether the sort descriptor sorts objects
+ * in ascending order (YES) or descending order (NO).
+ */
 - (BOOL) ascending;
-- (NSComparisonResult) compareObject: (id) object1 toObject: (id) object2;
+
+/** Returns the result of comparing object1 to object2 using the property
+ * whose key is defined in the receiver and using the selector of the
+ * receiver.  If the receiver performs a descending order sort, the
+ * result of this comparison is the opposite of that prroduced by
+ * applying the selector.
+ */
+- (NSComparisonResult) compareObject: (id)object1 toObject: (id)object2;
+
+/** Initialises the receiver for comparisons using the 'compare:' selector
+ * and the specified key and ordering.
+ */
 - (id) initWithKey: (NSString *)key
 	 ascending: (BOOL)ascending;
+
+/** <init />
+ * Initialises the receiver to perform comparisons in the specified order
+ * using selector to compar the property key of each object.
+ */
 - (id) initWithKey: (NSString *)key
          ascending: (BOOL)ascending
           selector: (SEL)selector;
+
+/** Returns the key used to obtain the property on which comparisons are based.
+ */
 - (NSString *) key;
+
+/** Returns the selector used to compare the properties of objects.
+ */
 - (SEL) selector;
+
+/** Returns a copy of the receiver which compares and sorts in reversed
+ * order.
+ */
 - (id) reversedSortDescriptor;
 @end
 
 @interface NSArray (NSSortDescriptorSorting)
 
+/**
+ * Produces a sorted array using the mechanism described for
+ * [NSMutableArray-sortUsingDescriptors:]
+ */
 - (NSArray *) sortedArrayUsingDescriptors: (NSArray *)sortDescriptors;
 
 @end
diff --git a/Source/NSSortDescriptor.m b/Source/NSSortDescriptor.m
index cfc4cd3ab..ebd0546ac 100644
--- a/Source/NSSortDescriptor.m
+++ b/Source/NSSortDescriptor.m
@@ -43,15 +43,21 @@
 - (NSComparisonResult) compareObject: (id) object1 toObject: (id) object2
 {
   NSComparisonResult result;
-  id comparedKey1 = [object1 valueForKeyPath: _key],
-     comparedKey2 = [object2 valueForKeyPath: _key];
+  id comparedKey1 = [object1 valueForKeyPath: _key];
+  id comparedKey2 = [object2 valueForKeyPath: _key];
 
   result = (NSComparisonResult) [comparedKey1 performSelector: _selector
                                                    withObject: comparedKey2];
-
-  if (_ascending != YES)
+  if (_ascending == NO)
     {
-      result = -result;
+      if (result == NSOrderedAscending)
+	{
+	  result = NSOrderedDescending;
+	}
+      else if (result == NSOrderedDescending)
+	{
+	  result = NSOrderedAscending;
+	}
     }
 
   return result;