Document that AnyVal "box" and "unbox" are implemented by BoxesRunTime

[scabug]

As discussed in #6710 and on scala-lang [1], the "box" and "unbox" methods of AnyVal classes (except Unit) are not actually implemented by the code in AnyVal [2].

Instead, the real implementation comes from BoxesRunTime (e.g. [3]). This is functionally different, creating potential for confusion.

As per the scala-lang discussion and #6710, changing the AnyVal code itself would have too much potential impact and thus be too risky. Documenting the behaviour would be a safer option.

From Paul Phillips' comment:

"If we're not using it in generated code and don't intend to, the ideal change is probably to deprecate it and then remove it. Next best (and to do regardless) is to document the behavior and the fact that it isn't actually used by the compiler." [4]

Source code of AnyVal classes and screenshots of documentation after

ant all.clean
ant build
./tools/codegen-anyvals
ANT_OPTS="-Xms512M -Xmx1024M -Xss1M -XX:MaxPermSize=128M" ant docs

attached.

[1] https://groups.google.com/d/topic/scala-language/kBQnJ3XuKeM/discussion
[2] https://github.com/scala/scala/blob/master/src/compiler/scala/tools/cmd/gen/AnyVals.scala#L2321
[3] https://github.com/scala/scala/blob/master/src/library/scala/runtime/BoxesRunTime.java#L87
[4] https://groups.google.com/d/msg/scala-language/kBQnJ3XuKeM/qvLnORIiXqAJ

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-6898?orig=1
Reporter: @demobox
Affected Versions: 2.10.0-RC5
Attachments:

• anyvals-src.zip (created on Dec 31, 2012 1:08:27 PM UTC, 18533 bytes)
• Boolean-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 38194 bytes)
• Byte-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 34195 bytes)
• Char-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 32471 bytes)
• Double.png (created on Dec 31, 2012 1:08:27 PM UTC, 24307 bytes)
• Float-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 26796 bytes)
• Int-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 29609 bytes)
• Long-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 28584 bytes)
• Short-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 32382 bytes)
• Unit-doc.png (created on Dec 31, 2012 1:08:27 PM UTC, 19152 bytes)

[scabug]

@demobox said:
Commit at https://github.com/demobox/scala/commit/719b86a3869f222bb37790faa4b6e9105cde4b1d

[scabug]

Lars Hupel (larsrh) said:
Is there any reason why the unbox methods shouldn't be deprecated for 2.11?

[scabug]

@demobox said:
Submitted pull request based on suggestion by @jsuereth:

scala/scala#2284