while reviewing this i'm left wondering why import convert. wrapAsScala._ is fine while import JavaConversions._ is not - could you add this to the doc of wrapAs[Sc|J]a[l|v]a (or some better place if you find one)?

or maybe there's an overview on JavaConverters somewhere already that explains everything?

@lrytz Funny you should mention that great minds think alike. I don't know if I linked to the paulp refactor that gave us the package object. It comes down to naming. I don't know between JavaConverters and JavaConversions, but wrapAsScala is distinguishable from decorateAsScala. Maybe. An alternate fix would be to rename JavaConversions as JavaPerversions. That was tempting. But it comes down to that JavaConverters is the public-facing or newbie-facing API, and the xxxAsScala are based on the principle of making things possible if you know what you're doing. I don't claim to know what I'm doing, but at least I can remember that decorateAsScala adds the method and the other one, wrapAsScala, is the magical conversion. How do I remember not to use wrapAsScala? Because "wrap" means "burrito" means "Chipotle" where I know not to eat anymore. I don't know if that means "Chipotle" is a monad.

Thanks for clarifying!

I'm not decided if we should also deprecate JavaConverters or not. I don't like that it's second way to do the same thing as collection.convert.decorateAll. It's also in a different namespace, so understanding how it relates to the package object adds to the cognitive load. But as you say, it guides newbies towards the decorators, while the package objects puts the evil burritos right next to the decorators.

Maybe the convert package object could itself extend DecorateAsJava with DecorateAsScala and continue to provide the fields it currently has? Then the recommendation would be to import collection.convert. There's a danger that newbies will write collection.convert._ and get the implicit wrappers... Opinions welcome.

Either way, I'll do an overhaul of the documentation. There's some good input on this question on stackoverflow, in particular the comment saying "I think whoever created those classes was stoned".

• http://stackoverflow.com/questions/8301947/what-is-the-difference-between-javaconverters-and-javaconversions-in-scala

Another thread to pull is the JavaConversion object in package concurrent. I think we should include its conversions into collection.convert, which already handles multiple kinds of collections (mutable, immutable).

• https://github.com/scala/scala/blob/2.12.x/src/library/scala/concurrent/JavaConversions.scala

I think my favorite is to deprecate JavaConverters and rename the fields in the convert package object, something like

package object convert {
  val explicitAsJava
  val explicitAsScala
  val explicitConversions

  val implicitToJava
  val implicitToScala
  val implicitConversions
}

And improve the documentation.

Just read the new comments. I don't disagree with them. My only intuition is that, as a newbie, I like to import foo._ and try something. Also, will changing names in convert._ require deprecation cycle? Leaving JavaConverters as one-stop-shop and convert._ as for-experts is simple.

There's a danger that newbies will write collection.convert._ and get the implicit wrappers

why even keep those wrappers around at all?

i.e., why keep any JavaConversions around?

I'm all for simplifying further. I also don't see any benefit in providing separate asScala / asJava imports, so that leaves us with a single non-deprecated object that extends DecorateAsJava with DecorateAsScala. In that case I think we should just keep the existing JavaConverters.

All of the following would be deprecated

• the convert package object
• the objects JavaConversions, convert.WrapAs*, convert.Wrappers, convert.Decorators
• the traits convert.WrapAsScala / convert.WrapAsJava

The convert package would just hold implementations but not actually be used directly by users.

Although Lukas has a different favorite deprecation on any given day, I'll run with his last instructions.

don't read it as instructions, i'm also not sure if this is where we'll find consensus

lrytz gave me the idea to totally change my mind. What I really wanted to do was mark the undesired implicits with deprecatedImplicitly so that they are not selected by implicit search. It would be especially neat if the behavior of deprecatedImplicitly were not just to emit the warning, but to remove the conversion from candidacy under -deprecation, emit a warning about that, and proceed with implicit search without it.

Calling the methods explicitly is fine.

@som-snytt Could you create a ticket for that? :-)

JavaConversions receives mention https://groups.google.com/forum/#!topic/scala-sips/wP6dL8nIAQs

Now I understand the test around Map.get. I was actually googling for deprecating implicits.

Linked in there is retronym's vote against deprecating JavaConversions.

@lrytz @SethTisue Modulo I broke something, the last commit proposes: JavaConverters contains the extension methods plus the converter methods themselves, so the same import is useful for doing an explicit asScalaIterator(javaIterator) and so on.

The implicit conversions from JavaConversions are available in convert.ImplicitConversions. There have been a few votes for making that possible, including @retronym in a previous thread. I think the namespace makes the road sign clear, "Welcome to Dangerville." Turn right onto Easy St.

The endgame is to retain JavaConverters, convert.{Wrappers, ImplicitConversions, Decorate*}.

Possibly everything except JavaConverters and ImplicitConversions should be private[collection]. WDY'AT? What do y'all think?

The implicit conversions from JavaConversions are available in convert.ImplicitConversions

I couldn't find those - did you push your latest work?

Forgot to add the new file. What's not obvious in the last commit is that I went through the docs fixing wrong names. I didn't try to make it gleam with polish; hard to keep so many docs up to date.

Re-submitted in #5109