sane semantics for Symbols.companionSymbol

While playing with tests for Type.companionType, I figured out that
companionSymbol isn’t what it seems to be:

scala> ScalaPackage.companionSymbol
res5: $r.intp.global.Symbol = <none>

scala> ScalaPackageClass.companionSymbol
res6: $r.intp.global.Symbol = package scala

Or even funnier observation:

scala> class C; object C
defined class C
defined object C

scala> val classC = typeOf[C].typeSymbol
classC: $r.intp.global.Symbol = class C

scala> val moduleC = classC.companionSymbol
moduleC: $r.intp.global.Symbol = object C

scala> classC.companionSymbol == moduleC
res0: Boolean = true

scala> moduleC.companionSymbol == classC
res1: Boolean = true

scala> moduleC.moduleClass.companionSymbol == moduleC
res2: Boolean = true

Of course, I rushed to clean this up, so that `companionSymbol` only
returns something other than NoSymbol if the target has a companion in
the common sense, not wrt the internal “class with the same name in the
same package” convention of scalac, and that `companionSymbol` for
module classes is a class, not a source module.

Unfortunately it’s not that easy, because api.Symbol#companionSymbol
has the same name as internal.Symbol#companionSymbol, so we can’t change
the behavior of the former without changing the behavior of the latter.

Therefore I deprecated api.Symbol#companionSymbol and introduced a replacement
called api.Symbol#companion with sane semantics.