1 files changed, 13 insertions, 0 deletions
diff --git a/src/library/scala/collection/mutable/StringBuilder.scala b/src/library/scala/collection/mutable/StringBuilder.scala
index 6c3715e560..73d3778650 100644
--- a/src/library/scala/collection/mutable/StringBuilder.scala
+++ b/src/library/scala/collection/mutable/StringBuilder.scala
@@ -432,11 +432,24 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
 
   /** Returns a new String representing the data in this sequence.
    *
+   *  @note    because toString is inherited from AnyRef and used for
+   *           many purposes, it is better practice to call mkString
+   *           to obtain a StringBuilder result.
    *  @return  the current contents of this sequence as a String
    */
   override def toString = underlying.toString
+
+  /** Returns a new String representing the data in this sequence.
+   *
+   *  @return  the current contents of this sequence as a String
+   */
   override def mkString = toString
 
+  /** Returns the result of this Builder, which in the case
+   *  of StringBuilders is a StringBuilder (not a String.)
+   *
+   *  @return  this StringBuilder
+   */
   def result(): StringBuilder = this
 }