Add some extra details on the name encoding scheme

Author: smarter

compiler/src/dotty/tools/dotc/util/NameTransformer.scala

@@ -48,6 +48,11 @@ object NameTransformer {
  /** Replace operator symbols by corresponding expansion strings, and replace
  * characters that are not valid Java identifiers by "$u" followed by the
  * character's unicode expansion.
+ * Note that no attempt is made to escape the use of '$' in `name`: blindly
+ * escaping them might make it impossible to call some platform APIs. This
+ * unfortunately means that `decode(encode(name))` might not be equal to
+ * `name`, this is considered acceptable since '$' is a reserved character in
+ * the Scala spec as well as the Java spec.
  */
  def encode(name: SimpleName): SimpleName = {
  var buf: StringBuilder = null