added comments and made some changes suggested by reviewers; still not in the build

string/public/nsReadableUtils.h

@@ -28,12 +28,64 @@
 
 #include "nsAReadableString.h"
 
-char* ToNewCString( const nsAReadableString& );
-char* ToNewCString( const nsAReadableCString& );
 
-PRUnichar* ToNewUnicode( const nsAReadableString& );
-PRUnichar* ToNewUnicode( const nsAReadableCString& );
+  /**
+   * Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * Performs a lossy encoding conversion by chopping 16-bit wide characters down to 8-bits wide while copying |aSource| to your new buffer.
+   * This conversion is not well defined; but it reproduces legacy string behavior.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource a 16-bit wide string
+   * @return a new |char| buffer you must free with |nsMemory::Free|.
+   */
+char* ToNewCString( const nsAReadableString& aSource );
 
-PRBool IsASCII( const nsAReadableString& );
+
+  /**
+   * Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource an 8-bit wide string
+   * @return a new |char| buffer you must free with |nsMemory::Free|.
+   */
+char* ToNewCString( const nsAReadableCString& aSource );
+
+
+  /**
+   * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource a 16-bit wide string
+   * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|.
+   */
+PRUnichar* ToNewUnicode( const nsAReadableString& aSource );
+
+
+  /**
+   * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * Performs an encoding conversion by 0-padding 8-bit wide characters up to 16-bits wide while copying |aSource| to your new buffer.
+   * This conversion is not well defined; but it reproduces legacy string behavior.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource an 8-bit wide string
+   * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|.
+   */
+PRUnichar* ToNewUnicode( const nsAReadableCString& aSource );
+
+
+  /**
+   * Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F).
+   *
+   * @param aString a 16-bit wide string to scan
+   */
+PRBool IsASCII( const nsAReadableString& aString );
 
 #endif // !defined(nsReadableUtils_h___)

string/src/nsReadableUtils.cpp

@@ -28,6 +28,11 @@
 
 
 
+
+
+  /**
+   * A character sink that performs a |reinterpret_cast| style conversion between character types.
+   */
 template <class FromCharT, class ToCharT>
 class LossyConvertEncoding
   {
@@ -59,6 +64,15 @@ class LossyConvertEncoding
       output_type* mDestination;
   };
 
+
+
+  /**
+   * A helper function that allocates a buffer of the desired character type big enough to hold a copy of the supplied string (plus a zero terminator).
+   *
+   * @param aSource an string you will eventually be making a copy of
+   * @return a new buffer (of the type specified by the second parameter) which you must free with |nsMemory::Free|.
+   *
+   */
 template <class FromCharT, class ToCharT>
 inline
 ToCharT*
@@ -107,8 +121,7 @@ ToNewUnicode( const nsAReadableCString& aSource )
 PRBool
 IsASCII( const nsAReadableString& aString )
   {
-
-    const PRUnichar NOT_ASCII = PRUnichar(~0x007F);
+    static const PRUnichar NOT_ASCII = PRUnichar(~0x007F);
 
 
     // Don't want to use |copy_string| for this task, since we can stop at the first non-ASCII character

xpcom/ds/nsReadableUtils.cpp

@@ -28,6 +28,11 @@
 
 
 
+
+
+  /**
+   * A character sink that performs a |reinterpret_cast| style conversion between character types.
+   */
 template <class FromCharT, class ToCharT>
 class LossyConvertEncoding
   {
@@ -59,6 +64,15 @@ class LossyConvertEncoding
       output_type* mDestination;
   };
 
+
+
+  /**
+   * A helper function that allocates a buffer of the desired character type big enough to hold a copy of the supplied string (plus a zero terminator).
+   *
+   * @param aSource an string you will eventually be making a copy of
+   * @return a new buffer (of the type specified by the second parameter) which you must free with |nsMemory::Free|.
+   *
+   */
 template <class FromCharT, class ToCharT>
 inline
 ToCharT*
@@ -107,8 +121,7 @@ ToNewUnicode( const nsAReadableCString& aSource )
 PRBool
 IsASCII( const nsAReadableString& aString )
   {
-
-    const PRUnichar NOT_ASCII = PRUnichar(~0x007F);
+    static const PRUnichar NOT_ASCII = PRUnichar(~0x007F);
 
 
     // Don't want to use |copy_string| for this task, since we can stop at the first non-ASCII character

xpcom/ds/nsReadableUtils.h

@@ -28,12 +28,64 @@
 
 #include "nsAReadableString.h"
 
-char* ToNewCString( const nsAReadableString& );
-char* ToNewCString( const nsAReadableCString& );
 
-PRUnichar* ToNewUnicode( const nsAReadableString& );
-PRUnichar* ToNewUnicode( const nsAReadableCString& );
+  /**
+   * Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * Performs a lossy encoding conversion by chopping 16-bit wide characters down to 8-bits wide while copying |aSource| to your new buffer.
+   * This conversion is not well defined; but it reproduces legacy string behavior.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource a 16-bit wide string
+   * @return a new |char| buffer you must free with |nsMemory::Free|.
+   */
+char* ToNewCString( const nsAReadableString& aSource );
 
-PRBool IsASCII( const nsAReadableString& );
+
+  /**
+   * Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource an 8-bit wide string
+   * @return a new |char| buffer you must free with |nsMemory::Free|.
+   */
+char* ToNewCString( const nsAReadableCString& aSource );
+
+
+  /**
+   * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource a 16-bit wide string
+   * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|.
+   */
+PRUnichar* ToNewUnicode( const nsAReadableString& aSource );
+
+
+  /**
+   * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * Performs an encoding conversion by 0-padding 8-bit wide characters up to 16-bits wide while copying |aSource| to your new buffer.
+   * This conversion is not well defined; but it reproduces legacy string behavior.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource an 8-bit wide string
+   * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|.
+   */
+PRUnichar* ToNewUnicode( const nsAReadableCString& aSource );
+
+
+  /**
+   * Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F).
+   *
+   * @param aString a 16-bit wide string to scan
+   */
+PRBool IsASCII( const nsAReadableString& aString );
 
 #endif // !defined(nsReadableUtils_h___)

xpcom/string/public/nsReadableUtils.h

@@ -28,12 +28,64 @@
 
 #include "nsAReadableString.h"
 
-char* ToNewCString( const nsAReadableString& );
-char* ToNewCString( const nsAReadableCString& );
 
-PRUnichar* ToNewUnicode( const nsAReadableString& );
-PRUnichar* ToNewUnicode( const nsAReadableCString& );
+  /**
+   * Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * Performs a lossy encoding conversion by chopping 16-bit wide characters down to 8-bits wide while copying |aSource| to your new buffer.
+   * This conversion is not well defined; but it reproduces legacy string behavior.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource a 16-bit wide string
+   * @return a new |char| buffer you must free with |nsMemory::Free|.
+   */
+char* ToNewCString( const nsAReadableString& aSource );
 
-PRBool IsASCII( const nsAReadableString& );
+
+  /**
+   * Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource an 8-bit wide string
+   * @return a new |char| buffer you must free with |nsMemory::Free|.
+   */
+char* ToNewCString( const nsAReadableCString& aSource );
+
+
+  /**
+   * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource a 16-bit wide string
+   * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|.
+   */
+PRUnichar* ToNewUnicode( const nsAReadableString& aSource );
+
+
+  /**
+   * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
+   *
+   * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|.
+   * Performs an encoding conversion by 0-padding 8-bit wide characters up to 16-bits wide while copying |aSource| to your new buffer.
+   * This conversion is not well defined; but it reproduces legacy string behavior.
+   * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.
+   *
+   * @param aSource an 8-bit wide string
+   * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|.
+   */
+PRUnichar* ToNewUnicode( const nsAReadableCString& aSource );
+
+
+  /**
+   * Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F).
+   *
+   * @param aString a 16-bit wide string to scan
+   */
+PRBool IsASCII( const nsAReadableString& aString );
 
 #endif // !defined(nsReadableUtils_h___)

xpcom/string/src/nsReadableUtils.cpp

@@ -28,6 +28,11 @@
 
 
 
+
+
+  /**
+   * A character sink that performs a |reinterpret_cast| style conversion between character types.
+   */
 template <class FromCharT, class ToCharT>
 class LossyConvertEncoding
   {
@@ -59,6 +64,15 @@ class LossyConvertEncoding
       output_type* mDestination;
   };
 
+
+
+  /**
+   * A helper function that allocates a buffer of the desired character type big enough to hold a copy of the supplied string (plus a zero terminator).
+   *
+   * @param aSource an string you will eventually be making a copy of
+   * @return a new buffer (of the type specified by the second parameter) which you must free with |nsMemory::Free|.
+   *
+   */
 template <class FromCharT, class ToCharT>
 inline
 ToCharT*
@@ -107,8 +121,7 @@ ToNewUnicode( const nsAReadableCString& aSource )
 PRBool
 IsASCII( const nsAReadableString& aString )
   {
-
-    const PRUnichar NOT_ASCII = PRUnichar(~0x007F);
+    static const PRUnichar NOT_ASCII = PRUnichar(~0x007F);
 
 
     // Don't want to use |copy_string| for this task, since we can stop at the first non-ASCII character