--- a/xpcom/string/nsTString.h
+++ b/xpcom/string/nsTString.h
@@ -770,24 +770,40 @@ public:
   {
     Assign(aTuple);
     return *this;
   }
 };
 
 
 /**
- * getter_Copies support for use with raw string out params:
+ * getter_Copies support for adopting raw string out params that are
+ * heap-allocated, e.g.:
  *
- *    NS_IMETHOD GetBlah(char**);
+ *    char* gStr;
+ *    void GetBlah(char** aStr)
+ *    {
+ *      *aStr = strdup(gStr);
+ *    }
  *
- *    void some_function()
+ *    // This works, but is clumsy.
+ *    void Inelegant()
  *    {
- *      nsXPIDLCString blah;
- *      GetBlah(getter_Copies(blah));
+ *      char* buf;
+ *      GetBlah(&buf);
+ *      nsCString str;
+ *      str.Adopt(buf);
+ *      // ...
+ *    }
+ *
+ *    // This is nicer.
+ *    void Elegant()
+ *    {
+ *      nsCString str;
+ *      GetBlah(getter_Copies(str));
  *      // ...
  *    }
  */
 class MOZ_STACK_CLASS nsTGetterCopies_CharT
 {
 public:
   typedef CharT char_type;
 
@@ -807,14 +823,15 @@ public:
     return &mData;
   }
 
 private:
   nsTSubstring_CharT& mString;
   char_type* mData;
 };
 
+// See the comment above nsTGetterCopies_CharT for how to use this.
 inline nsTGetterCopies_CharT
 getter_Copies(nsTSubstring_CharT& aString)
 {
   return nsTGetterCopies_CharT(aString);
 }
 

--- a/xpcom/string/nsTSubstring.h
+++ b/xpcom/string/nsTSubstring.h
@@ -521,16 +521,19 @@ public:
     return *this;
   }
   self_type& operator=(const substring_tuple_type& aTuple)
   {
     Assign(aTuple);
     return *this;
   }
 
+  // Adopt a heap-allocated char sequence for this string; is Voided if aData
+  // is null. Useful for e.g. converting an strdup'd C string into an
+  // nsCString. See also getter_Copies(), which is a useful wrapper.
   void NS_FASTCALL Adopt(char_type* aData, size_type aLength = size_type(-1));
 
 
   /**
    * buffer manipulation
    */
 
   void NS_FASTCALL Replace(index_type aCutStart, size_type aCutLength,