docs. no review

1 files changed, 22 insertions, 19 deletions

diff --git a/src/library/scala/collection/mutable/BufferProxy.scala b/src/library/scala/collection/mutable/BufferProxy.scala
index 71c2bc4ca1..983572452b 100644
--- a/src/library/scala/collection/mutable/BufferProxy.scala
+++ b/src/library/scala/collection/mutable/BufferProxy.scala
@@ -16,13 +16,18 @@ import generic._
 import script._
 
 /** This is a simple proxy class for <a href="Buffer.html"
- *  target="contentFrame"><code>scala.collection.mutable.Buffer</code></a>.
+ *  target="contentFrame">`scala.collection.mutable.Buffer`</a>.
  *  It is most useful for assembling customized set abstractions
  *  dynamically using object composition and forwarding.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 16/04/2004
  *  @since   1
+ *
+ *  @tparam A     type of the elements the buffer proxy contains.
+ *
+ *  @define Coll BufferProxy
+ *  @define coll buffer proxy
  */
 trait BufferProxy[A] extends Buffer[A] with Proxy {
 
@@ -63,10 +68,10 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
               "Use `clone() ++=` if you intend to create a new collection.")
   override def ++(xs: TraversableOnce[A]): Buffer[A] = self.++(xs)
 
-  /** Appends a number of elements provided by a traversable object
-   *  via its <code>foreach</code> method.
+  /** Appends a number of elements provided by a traversable object.
    *
-   *  @param iter  the traversable object.
+   *  @param xs   the traversable object.
+   *  @return     a reference to this $coll.
    */
   override def ++=(xs: TraversableOnce[A]): this.type = { self.++=(xs); this }
 
@@ -76,10 +81,9 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def append(elems: A*) { self.++=(elems) }
 
-  /** Appends a number of elements provided by a traversable object
-   *  via its <code>foreach</code> method.
+  /** Appends a number of elements provided by a traversable object.
    *
-   *  @param iter  the traversable object.
+   *  @param xs   the traversable object.
    */
   override def appendAll(xs: TraversableOnce[A]) { self.appendAll(xs) }
 
@@ -87,6 +91,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    *  the identity of the buffer.
    *
    *  @param elem  the element to append.
+   *  @return      a reference to this $coll.
    */
   def +=:(elem: A): this.type = { self.+=:(elem); this }
 
@@ -98,26 +103,25 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def prepend(elems: A*) { self.prependAll(elems) }
 
-  /** Prepends a number of elements provided by a traversable object
-   *  via its <code>foreach</code> method. The identity of the
-   *  buffer is returned.
+  /** Prepends a number of elements provided by a traversable object.
+   *  The identity of the buffer is returned.
    *
    *  @param xs  the traversable object.
    */
   override def prependAll(xs: TraversableOnce[A]) { self.prependAll(xs) }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert the new elements at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a
+   *  one. Instead, it will insert the new elements at index `n`.
    *
    *  @param n      the index where a new element will be inserted.
    *  @param elems  the new elements to insert.
    */
   override def insert(n: Int, elems: A*) { self.insertAll(n, elems) }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert a new element at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a
+   *  one. Instead, it will insert a new element at index `n`.
    *
    *  @param n     the index where a new element will be inserted.
    *  @param iter  the iterable object providing all elements to insert.
@@ -126,8 +130,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   override def insertAll(n: Int, iter: scala.collection.Traversable[A]): Unit = self.insertAll(n, iter)
 
-  /** Replace element at index <code>n</code> with the new element
-   *  <code>newelem</code>.
+  /** Replace element at index `n` with the new element `newelem`.
    *
    *  @param n       the index of the element to replace.
    *  @param newelem the new element.
@@ -152,7 +155,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   /** Return a clone of this buffer.
    *
-   *  @return a <code>Buffer</code> with the same elements.
+   *  @return a `Buffer` with the same elements.
    */
   override def clone(): Buffer[A] = new BufferProxy[A] {
     def self = BufferProxy.this.self.clone()