Clean, refine scope, add comments

- Tidy the code (space, newline,...)
- Refine the scope by making more things private
- Add explaination and doc comments (mostly to help reviewer)

Author: PaulCoral

compiler/src/dotty/tools/dotc/transform/CheckUnused.scala

@@ -14,7 +14,6 @@ import dotty.tools.dotc.report
 import dotty.tools.dotc.reporting.Message
 import dotty.tools.dotc.typer.ImportInfo
 import dotty.tools.dotc.util.Property
-import dotty.tools.dotc.transform.CheckUnused.UnusedData.UnusedResult
 import dotty.tools.dotc.core.Mode
 import dotty.tools.dotc.core.Types.TypeTraverser
 import dotty.tools.dotc.core.Types.Type
@@ -34,6 +33,10 @@ import dotty.tools.dotc.core.Names.Name
 class CheckUnused extends Phase:
   import CheckUnused.UnusedData
 
+  /**
+   * The key used to retrieve the "unused entity" analysis metadata,
+   * from the compilation `Context`
+   */
   private val _key = Property.Key[UnusedData]
 
   override def phaseName: String = CheckUnused.phaseName
@@ -98,11 +101,13 @@ class CheckUnused extends Phase:
     end traverse
   end traverser
 
+  /** This is a type traverser which catch some special Types not traversed by the term traverser above */
   private def typeTraverser(dt: (UnusedData => Any) => Unit)(using Context) = new TypeTraverser:
     override def traverse(tp: Type): Unit = tp match
       case AnnotatedType(_, annot) => dt(_.registerUsed(annot.symbol, None))
       case _ => traverseChildren(tp)
 
+  /** Do the actual reporting given the result of the anaylsis */
   private def reportUnused(res: UnusedData.UnusedResult)(using Context): Unit =
     import CheckUnused.WarnTypes
     res.warnings.foreach { s =>
@@ -127,7 +132,7 @@ object CheckUnused:
   val phaseName: String = "checkUnused"
   val description: String = "check for unused elements"
 
-  enum WarnTypes:
+  private enum WarnTypes:
     case Imports
     case LocalDefs
     case ExplicitParams
@@ -142,6 +147,7 @@ object CheckUnused:
    * - usage
    */
   private class UnusedData:
+    import dotty.tools.dotc.transform.CheckUnused.UnusedData.UnusedResult
     import collection.mutable.{Set => MutSet, Map => MutMap, Stack => MutStack}
     import dotty.tools.dotc.core.Symbols.Symbol
     import UnusedData.ScopeType
@@ -195,7 +201,12 @@ object CheckUnused:
       val annotSym = sym.denot.annotations.map(_.symbol)
       registerUsed(annotSym)
 
-    /** Register a found (used) symbol */
+    /**
+     * Register a found (used) symbol along with its name
+     *
+     * The optional name will be used to target the right import
+     * as the same element can be imported with different renaming
+     */
     def registerUsed(sym: Symbol, name: Option[Name])(using Context): Unit =
       if !isConstructorOfSynth(sym) then
         usedInScope.top += ((sym, sym.isAccessibleAsIdent, name))
@@ -336,9 +347,16 @@ object CheckUnused:
     private def isConstructorOfSynth(sym: Symbol)(using Context): Boolean =
       sym.exists && sym.isConstructor && sym.owner.isPackageObject && sym.owner.is(Synthetic)
 
+    /**
+     * This is used to avoid reporting the parameters of the synthetic main method
+     * generated by `@main`
+     */
     private def isSyntheticMainParam(sym: Symbol)(using Context): Boolean =
       sym.exists && ctx.platform.isMainMethod(sym.owner) && sym.owner.is(Synthetic)
 
+    /**
+     * This is used to ignore exclusion imports (i.e. import `qual`.{`member` => _})
+     */
     private def isImportExclusion(sel: ImportSelector): Boolean = sel.renamed match
       case untpd.Ident(name) => name == StdNames.nme.WILDCARD
       case _ => false
@@ -376,21 +394,22 @@ object CheckUnused:
           selector.orElse(wildcard) // selector with name or wildcard (or given)
         else
           None
-
   end UnusedData
 
-  object UnusedData:
+  private object UnusedData:
       enum ScopeType:
         case Local
         case Template
         case Other
 
       object ScopeType:
+        /** return the scope corresponding to the enclosing scope of the given tree */
         def fromTree(tree: tpd.Tree): ScopeType = tree match
           case _:tpd.Template => Template
           case _:tpd.Block => Local
           case _ => Other
 
+      /** A container for the results of the used elements analysis */
       case class UnusedResult(warnings: List[(dotty.tools.dotc.util.SrcPos, WarnTypes)], usedImports: List[(tpd.Import, untpd.ImportSelector)])
 end CheckUnused