diff --git a/ChangeLog b/ChangeLog
index 8a1275335..d8e92378b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-11-03  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/NSString.m: ([stringByAddingPercentEscapesUsingEncoding:])
+	Improved documentation.
+
 2006-11-02  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/NSString.m: ([stringByAddingPercentEscapesUsingEncoding:])
diff --git a/Source/NSString.m b/Source/NSString.m
index 905fbc634..22e6e9a97 100644
--- a/Source/NSString.m
+++ b/Source/NSString.m
@@ -1330,9 +1330,15 @@ handle_printf_atsign (FILE *stream,
  * ASCII characters.  The byte values escaped are any below 32 and any
  * above 126 as well as 32 (space), 34 ("), 35 (#), 37 (%), 60 (&lt;),
  * 62 (&gt;), 91 ([), 92 (\), 93 (]), 94 (^), 96 (~), 123 ({), 124 (|),
- * and 125 (}).
+ * and 125 (}).<br />
  * Returns nil if the receiver cannot be represented using the specified
- * encoding.
+ * encoding.<br />
+ * NB. This behavior is MacOS-X (4.2) compatible, and it should be noted
+ * that it does <em>not</em> produce a string suitable for use as a field
+ * value in a url-encoded form as it does <strong>not</strong> escape the
+ * '+', '=' and '&amp;' characters used in such forms.  If you need to
+ * add a string as a form field value (or name) you must add percent
+ * escapes for those characters yourself.
  */
 - (NSString*) stringByAddingPercentEscapesUsingEncoding: (NSStringEncoding)e
 {