Document `IsInstanceOfEvaluator` using markdown style docstrings

1 files changed, 30 insertions, 28 deletions

diff --git a/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala b/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala
index 8bc4a2aa9..e6b1f5aac 100644
--- a/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala
+++ b/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala
@@ -7,43 +7,45 @@ import core._
 import Contexts.Context, Types._, Constants._, Decorators._, Symbols._
 import TypeUtils._, TypeErasure._, Flags._
 
-
 /** Implements partial evaluation of `sc.isInstanceOf[Sel]` according to:
- *
- *  +-------------+----------------------------+----------------------------+------------------+
- *  | Sel\sc      | trait                      | class                      | final class      |
- *  +-------------+----------------------------+----------------------------+------------------+
- *  | trait       |               ?            |               ?            | statically known |
- *  | class       |               ?            | false if classes unrelated | statically known |
- *  | final class | false if classes unrelated | false if classes unrelated | statically known |
- *  +-------------+----------------------------+----------------------------+------------------+
- *
- *  This is a generalized solution to raising an error on unreachable match
- *  cases and warnings on other statically known results of `isInstanceOf`.
- *
- *  Steps taken:
- *
- *  1.  evalTypeApply will establish the matrix and choose the appropriate
- *      handling for the case:
- *  2.  a) Sel/sc is a value class or scrutinee is `Any`
- *      b) handleStaticallyKnown
- *      c) falseIfUnrelated with `scrutinee <:< selector`
- *      d) handleFalseUnrelated
- *      e) leave as is (aka `happens`)
- *  3.  Rewrite according to step taken in `2`
- */
+  *
+  * | Sel\sc      | trait                      | class                      | final class      |
+  * | ----------: | :------------------------: | :------------------------: | :--------------: |
+  * | trait       |               ?            |               ?            | statically known |
+  * | class       |               ?            | false if classes unrelated | statically known |
+  * | final class | false if classes unrelated | false if classes unrelated | statically known |
+  *
+  * This is a generalized solution to raising an error on unreachable match
+  * cases and warnings on other statically known results of `isInstanceOf`.
+  *
+  * Steps taken:
+  *
+  * 1. `evalTypeApply` will establish the matrix and choose the appropriate
+  *    handling for the case:
+  *     - Sel/sc is a value class or scrutinee is `Any`
+  *     - `handleStaticallyKnown`
+  *     - `falseIfUnrelated` with `scrutinee <:< selector`
+  *     - `handleFalseUnrelated`
+  *     - leave as is (`happens`)
+  * 2. Rewrite according to steps taken in 1
+  */
 class IsInstanceOfEvaluator extends MiniPhaseTransform { thisTransformer =>
 
   import dotty.tools.dotc.ast.tpd._
 
-  def phaseName = "isInstanceOfEvaluator"
+  /** @inheritdoc */
+  val phaseName = "isInstanceOfEvaluator"
+
+  /** Transforms a [TypeApply](dotty.tools.dotc.ast.Trees.TypeApply) in order to
+    * evaluate an `isInstanceOf` check according to the rules defined above.
+    */
   override def transformTypeApply(tree: TypeApply)(implicit ctx: Context, info: TransformerInfo): Tree = {
     val defn = ctx.definitions
 
     /** Handles the four cases of statically known `isInstanceOf`s and gives
-     *  the correct warnings, or an error if statically known to be false in
-     *  match
-     */
+      * the correct warnings, or an error if statically known to be false in
+      * match
+      */
     def handleStaticallyKnown(select: Select, scrutinee: Type, selector: Type, inMatch: Boolean, pos: Position): Tree = {
       val scrutineeSubSelector = scrutinee <:< selector
       if (!scrutineeSubSelector && inMatch) {