Merge pull request #3841 from Ichoran/issue/5200

SI-5200  Incorrect advice for implementing mutable.Set in scaladoc

src/library/scala/collection/SetLike.scala

@@ -17,17 +17,16 @@ import parallel.ParSet
 /** A template trait for sets.
  *
  *  $setNote
+ *    '''Implementation note:'''
+ *    This trait provides most of the operations of a `Set` independently of its representation.
+ *    It is typically inherited by concrete implementations of sets.
  *  $setTags
  *  @since 2.8
  *
  *  @define setNote
  *
  *  A set is a collection that contains no duplicate elements.
  *
- *    '''Implementation note:'''
- *    This trait provides most of the operations of a `Set` independently of its representation.
- *    It is typically inherited by concrete implementations of sets.
- *
  *    To implement a concrete set, you need to provide implementations of the
  *    following methods:
  *    {{{

src/library/scala/collection/mutable/SetLike.scala

@@ -16,33 +16,34 @@ import scala.annotation.migration
 import parallel.mutable.ParSet
 
 /** A template trait for mutable sets of type `mutable.Set[A]`.
+ *
+ *    This trait provides most of the operations of a `mutable.Set` independently of its representation.
+ *    It is typically inherited by concrete implementations of sets.
+ *
+ *  $setNote
+ *
  *  @tparam A    the type of the elements of the set
  *  @tparam This the type of the set itself.
  *
- *  $setnote
- *
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since 2.8
  *
- *  @define setnote
- *  @note
- *    This trait provides most of the operations of a `mutable.Set` independently of its representation.
- *    It is typically inherited by concrete implementations of sets.
+ *  @define setNote
  *
  *    To implement a concrete mutable set, you need to provide implementations
  *    of the following methods:
  *    {{{
  *       def contains(elem: A): Boolean
  *       def iterator: Iterator[A]
  *       def += (elem: A): this.type
- *       def -= (elem: A): this.type</pre>
+ *       def -= (elem: A): this.type
  *    }}}
  *    If you wish that methods like `take`,
  *    `drop`, `filter` return the same kind of set,
  *    you should also override:
  *    {{{
- *       def empty: This</pre>
+ *       def empty: This
  *    }}}
  *    It is also good idea to override methods `foreach` and
  *    `size` for efficiency.