Fix documentatiion errors.

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

ChangeLog

@@ -1,3 +1,8 @@
+2007-03-19  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/NSDictionary.m: Correct errors in documentation about keys
+	being retained when they are in fact copied.
+
 2007-03-17  Adam Fedor  <fedor@gnu.org>
 
 	* config/config.trampoline.c: Check for proper CPU macro for Darwin

Source/NSDictionary.m

@@ -87,10 +87,11 @@ static SEL	appSel;
  *  retrieve multiple entries simultaneously, obtain sorted contents, and
  *  read/write from/to a serialized representation.</p>
  *
- *  <p>Both keys and values are retained by the implementation, and released
- *  when either their entry is dropped or the entire dictionary is deallocated.
- *  This differs from the implementation on OS X, where keys are copied instead
- *  of being retained and must therefore implement the [(NSCopying)] protocol.
+ *  <p>The keys are copied and values are retained by the implementation,
+ *  and both are released when either their entry is dropped or the entire
+ *  dictionary is deallocated.<br />
+ *  As in the OS X implementation, keys must therefore implement the
+ *  [(NSCopying)] protocol.
  *  </p>
  *
  *  <p>Objects of this class are immutable.  For a mutable version, use the
@@ -507,7 +508,10 @@ static SEL	appSel;
 /**
  * Initialise dictionary with the keys and values of otherDictionary.
  * If the shouldCopy flag is YES then the values are copied into the
- * newly initialised dictionary, otherwise they are simply retained.
+ * newly initialised dictionary, otherwise they are simply retained,
+ * on the assumption that it is safe to retain the keys from another
+ * dictionary since that other dictionary mwill have copied the keys
+ * originally to ensure that they are immutable.
  */
 - (id) initWithDictionary: (NSDictionary*)other
 		copyItems: (BOOL)shouldCopy
@@ -1155,9 +1159,9 @@ compareIt(id o1, id o2, void* context)
 /**
  *  Adds entry for aKey, mapping to anObject.  If either is nil, an exception
  *  is raised.  If aKey already in dictionary, the value it maps to is
- *  silently replaced.  aKey and anObject are both retained.  (This differs
- *  from OS X, where the key is copied and must therefore implement the
- *  [(NSCopying)] protocol.)
+ *  silently replaced.  The value anObject is retained, but aKey is copied
+ *  (because a dictionary key must be immutable) and must therefore implement
+ *  the [(NSCopying)] protocol.)
  */
 - (void) setObject: anObject forKey: (id)aKey
 {