SI-9684 Deprecate JavaConversions

Implicit conversions are now in package convert as ImplicitConversions,
ImplicitConversionsToScala and ImplicitConversionsToJava.

Deprecated WrapAsJava, WrapAsScala and the values in package object.

Improve documentation.

1 files changed, 37 insertions, 25 deletions

diff --git a/src/library/scala/collection/JavaConverters.scala b/src/library/scala/collection/JavaConverters.scala
index 58fbc5afa5..d48a1764e9 100644
--- a/src/library/scala/collection/JavaConverters.scala
+++ b/src/library/scala/collection/JavaConverters.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2006-2013, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2006-2016, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |    http://www.scala-lang.org/           **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -11,14 +11,12 @@ package collection
 
 import convert._
 
-// TODO: I cleaned all this documentation up in JavaConversions, but the
-// documentation in here is basically the pre-cleaned-up version with minor
-// additions.  Would be nice to have in one place.
-
-/** A collection of decorators that allow converting between
- *  Scala and Java collections using `asScala` and `asJava` methods.
+/** A variety of decorators that enable converting between
+ *  Scala and Java collections using extension methods, `asScala` and `asJava`.
+ *
+ *  The extension methods return adapters for the corresponding API.
  *
- *  The following conversions are supported via `asJava`, `asScala`
+ *  The following conversions are supported via `asScala` and `asJava`:
  *{{{
  *    scala.collection.Iterable               <=> java.lang.Iterable
  *    scala.collection.Iterator               <=> java.util.Iterator
@@ -27,25 +25,14 @@ import convert._
  *    scala.collection.mutable.Map            <=> java.util.Map
  *    scala.collection.mutable.concurrent.Map <=> java.util.concurrent.ConcurrentMap
  *}}}
- *  In all cases, converting from a source type to a target type and back
- *  again will return the original source object, e.g.
- *  {{{
- *    import scala.collection.JavaConverters._
- *
- *    val sl = new scala.collection.mutable.ListBuffer[Int]
- *    val jl : java.util.List[Int] = sl.asJava
- *    val sl2 : scala.collection.mutable.Buffer[Int] = jl.asScala
- *    assert(sl eq sl2)
- *  }}}
- *  The following conversions are also supported, but the
- *  direction from Scala to Java is done by the more specifically named methods:
- *  `asJavaCollection`, `asJavaEnumeration`, `asJavaDictionary`.
+ *  The following conversions are supported via `asScala` and through
+ *  specially-named extension methods to convert to Java collections, as shown:
  *{{{
- *    scala.collection.Iterable    <=> java.util.Collection
- *    scala.collection.Iterator    <=> java.util.Enumeration
- *    scala.collection.mutable.Map <=> java.util.Dictionary
+ *    scala.collection.Iterable    <=> java.util.Collection   (via asJavaCollection)
+ *    scala.collection.Iterator    <=> java.util.Enumeration  (via asJavaEnumeration)
+ *    scala.collection.mutable.Map <=> java.util.Dictionary   (via asJavaDictionary)
  *}}}
- *  In addition, the following one way conversions are provided via `asJava`:
+ *  In addition, the following one-way conversions are provided via `asJava`:
  *{{{
  *    scala.collection.Seq         => java.util.List
  *    scala.collection.mutable.Seq => java.util.List
@@ -56,6 +43,31 @@ import convert._
  *{{{
  *    java.util.Properties => scala.collection.mutable.Map
  *}}}
+ *  In all cases, converting from a source type to a target type and back
+ *  again will return the original source object. For example:
+ *  {{{
+ *    import scala.collection.JavaConverters._
+ *
+ *    val source = new scala.collection.mutable.ListBuffer[Int]
+ *    val target: java.util.List[Int] = source.asJava
+ *    val other: scala.collection.mutable.Buffer[Int] = target.asScala
+ *    assert(source eq other)
+ *  }}}
+ *  Alternatively, the conversion methods have descriptive names and can be invoked explicitly.
+ *  {{{
+ *    scala> val vs = java.util.Arrays.asList("hi", "bye")
+ *    vs: java.util.List[String] = [hi, bye]
+ *
+ *    scala> val ss = asScalaIterator(vs.iterator)
+ *    ss: Iterator[String] = non-empty iterator
+ *
+ *    scala> .toList
+ *    res0: List[String] = List(hi, bye)
+ *
+ *    scala> val ss = asScalaBuffer(vs)
+ *    ss: scala.collection.mutable.Buffer[String] = Buffer(hi, bye)
+ *  }}}
+ *
  *  @since  2.8.1
  */
 object JavaConverters extends DecorateAsJava with DecorateAsScala