More documentation for some Scala.js-specific methods.

Author: sjrd

src/dotty/tools/backend/sjs/JSCodeGen.scala

@@ -1946,6 +1946,10 @@ class JSCodeGen()(implicit ctx: Context) {
   }
 
   /** Boxes a value of the given type before `elimErasedValueType`.
+   *
+   *  This should be used when sending values to a JavaScript context, which
+   *  is erased/boxed at the IR level, although it is not erased at the
+   *  dotty/JVM level.
    *
    *  @param expr Tree to be boxed if needed.
    *  @param tpeEnteringElimErasedValueType The type of `expr` as it was
@@ -1969,6 +1973,10 @@ class JSCodeGen()(implicit ctx: Context) {
   }
 
   /** Unboxes a value typed as Any to the given type before `elimErasedValueType`.
+   *
+   *  This should be used when receiving values from a JavaScript context,
+   *  which is erased/boxed at the IR level, although it is not erased at the
+   *  dotty/JVM level.
    *
    *  @param expr Tree to be extracted.
    *  @param tpeEnteringElimErasedValueType The type of `expr` as it was

src/dotty/tools/backend/sjs/JSDefinitions.scala

@@ -178,6 +178,11 @@ final class JSDefinitions()(implicit ctx: Context) {
     if (cls.isClass && cls.owner == ScalaJSJSPackageClass) cls.asClass.name
     else EmptyTypeName
 
+  /** Is the given `cls` a class of the form `scala.scalajs.js.prefixN` where
+   *  `N` is a number.
+   *
+   *  This is similar to `isVarArityClass` in `Definitions.scala`.
+   */
   private def isScalaJSVarArityClass(cls: Symbol, prefix: Name): Boolean = {
     val name = scalajsClassName(cls)
     name.startsWith(prefix) && name.drop(prefix.length).forall(_.isDigit)

src/dotty/tools/backend/sjs/JSInterop.scala

@@ -24,22 +24,38 @@ object JSInterop {
   def isScalaJSDefinedJSClass(sym: Symbol)(implicit ctx: Context): Boolean =
     isJSType(sym) && !sym.hasAnnotation(jsdefn.JSNativeAnnot)
 
-  /** Should this symbol be translated into a JS getter? */
+  /** Should this symbol be translated into a JS getter?
+   *
+   *  This is true for any parameterless method, i.e., defined without `()`.
+   *  Unlike `SymDenotations.isGetter`, it applies to user-defined methods as
+   *  much as *accessor* methods created for `val`s and `var`s.
+   */
   def isJSGetter(sym: Symbol)(implicit ctx: Context): Boolean = {
     sym.info.firstParamTypes.isEmpty && ctx.atPhase(ctx.erasurePhase) { implicit ctx =>
       sym.info.isParameterless
     }
   }
 
-  /** Should this symbol be translated into a JS setter? */
+  /** Should this symbol be translated into a JS setter?
+   *
+   *  This is true for any method whose name ends in `_=`.
+   *  Unlike `SymDenotations.isGetter`, it applies to user-defined methods as
+   *  much as *accessor* methods created for `var`s.
+   */
   def isJSSetter(sym: Symbol)(implicit ctx: Context): Boolean =
     sym.name.isSetterName && sym.is(Method)
 
-  /** Should this symbol be translated into a JS bracket access? */
+  /** Should this symbol be translated into a JS bracket access?
+   *
+   *  This is true for methods annotated with `@JSBracketAccess`.
+   */
   def isJSBracketAccess(sym: Symbol)(implicit ctx: Context): Boolean =
     sym.hasAnnotation(jsdefn.JSBracketAccessAnnot)
 
-  /** Should this symbol be translated into a JS bracket call? */
+  /** Should this symbol be translated into a JS bracket call?
+   *
+   *  This is true for methods annotated with `@JSBracketCall`.
+   */
   def isJSBracketCall(sym: Symbol)(implicit ctx: Context): Boolean =
     sym.hasAnnotation(jsdefn.JSBracketCallAnnot)