Merge pull request #5437 from dotty-staging/add-tasty-reflect-documentation

Add documentation to TASTy reflect

Author: nicolasstucki

library/src/scala/tasty/reflect/Core.scala

@@ -124,19 +124,42 @@ trait Core {
   /** Workaround missing `|` types in Scala 2 to represent `Term | TypeTree` */
   type TermOrTypeTree /* Term | TypeTree */
 
-  /** Tree representing executable code written in the source */
+  /** Tree representing code written in the source */
   type Tree
+
+    /** Tree representing a pacakage clause in the source code */
     type PackageClause <: Tree
+
+    /** Tree representing a statement in the source code */
     type Statement <: Tree
+
+      /** Tree representing an import in the source code */
       type Import <: Statement
+
+      /** Tree representing a definition in the source code. It can be `PackageDef`, `ClassDef`, `TypeDef`, `DefDef` or `ValDef`*/
       type Definition <: Statement
+
+        /** Tree representing a package definition. This includes definitions in all source files. */
         type PackageDef <: Definition
+
+        /** Tree representing a class definition. This includes annonymus class definitions and the class of a module object. */
         type ClassDef <: Definition
+
+        /** Tree representing a type (paramter or member) definition in the source code. */
         type TypeDef <: Definition
+
+        /** Tree representing a method definition in the source code. */
         type DefDef <: Definition
+
+        /** Tree representing a value definition in the source code. This inclues `val`, `lazy val`, `var`, `object` and parameter defintions. */
         type ValDef <: Definition
+
+      /** Tree representing an expression in the source code. */
       type Term <: Statement
 
+        // TODO Add subtype types of Term for documentation? Or support refined bindings and add the types.
+
+
   /** Branch of a pattern match or catch clause */
   type CaseDef
 
@@ -145,30 +168,69 @@ trait Core {
 
   /** Pattern tree of the pattern part of a CaseDef */
   type Pattern
+
+    /** Pattern representing a value. This includes `1`, ```x``` and `_` */
     type Value <: Pattern
+
+    /** Pattern representing a `_ @ _` binding. */
     type Bind <: Pattern
+
+    /** Pattern representing a `Xyz(...)` unapply. */
     type Unapply <: Pattern
+
+    /** Pattern representing `X | Y | ...` alternatives. */
     type Alternative <: Pattern
+
+    /** Pattern representing a `x: Y` type test. */
     type TypeTest <: Pattern
 
-  /** Tree representing a type written in the source */
+  /** Type tree representing a type or a bounds written in the source */
   type TypeOrBoundsTree
+
+    /** Type tree representing a type written in the source */
     type TypeTree <: TypeOrBoundsTree
+
+      // TODO Add subtype types of TypeTree for documentation? Or support refined bindings and add the types.
+
+
+    /** Type tree representing a type bound written in the source */
     type TypeBoundsTree <: TypeOrBoundsTree
 
+  /** Type or bounds */
   type TypeOrBounds
+
+    /** NoPrefix for a type selection */
     type NoPrefix <: TypeOrBounds
+
+    /** Type bounds */
     type TypeBounds <: TypeOrBounds
+
+    /** A type */
     type Type <: TypeOrBounds
+
+    /** A type that is recursively defined */
     type RecursiveType <: Type
+
     // TODO can we add the bound back without an cake?
     // TODO is LambdaType really needed? ParamRefExtractor could be split into more precise extractors
+    /** Common abstraction for lambda types (MethodType, PolyType and TypeLambda). */
     type LambdaType[ParamInfo /*<: TypeOrBounds*/] <: Type
+
+      /** Type of the definition of a method taking a single list of parameters. It's return type may be a MethodType. */
       type MethodType <: LambdaType[Type]
+
+      /** Type of the definition of a method taking a list of type parameters. It's return type may be a MethodType. */
       type PolyType <: LambdaType[TypeBounds]
+
+      /** Type of the definition of a type lambda taking a list of type parameters. It's return type may be a TypeLambda. */
       type TypeLambda <: LambdaType[TypeBounds]
 
 
+  /** Import selectors:
+   *   * SimpleSelector: `.bar` in `import foo.bar`
+   *   * RenameSelector: `.{bar => baz}` in `import foo.{bar => baz}`
+   *   * OmitSelector: `.{bar => _}` in `import foo.{bar => _}`
+   */
   type ImportSelector
 
   /** Untyped identifier */
@@ -187,12 +249,26 @@ trait Core {
    *  Then can be compared with == to know if the definition is the same.
    */
   type Symbol
+
+    /** Symbol of a package defnition */
     type PackageSymbol <: Symbol
+
+    /** Symbol of a class defnition. This includes annonymus class definitions and the class of a module object. */
     type ClassSymbol <: Symbol
+
+    /** Symbol of a type (paramter or member) definition. */
     type TypeSymbol <: Symbol
+
+    /** Symbol representing a method definition. */
     type DefSymbol <: Symbol
+
+    /** Symbol representing a value definition. This inclues `val`, `lazy val`, `var`, `object` and parameter defintions. */
     type ValSymbol <: Symbol
+
+    /** Symbol representing a bind definition. */
     type BindSymbol <: Symbol
+
+    /** No symbol availabe. */
     type NoSymbol <: Symbol
 
 }

library/src/scala/tasty/reflect/FlagSet.scala

@@ -1,31 +1,85 @@
 package scala.tasty.reflect
 
 trait FlagSet {
+
+  /** Is this symbol `protected` */
   def isProtected: Boolean
+
+  /** Is this symbol `abstract` */
   def isAbstract: Boolean
+
+  /** Is this symbol `final` */
   def isFinal: Boolean
+
+  /** Is this symbol `sealed` */
   def isSealed: Boolean
+
+  /** Is this symbol `case` */
   def isCase: Boolean
+
+  /** Is this symbol `implicit` */
   def isImplicit: Boolean
+
+  /** Is this symbol `erased` */
   def isErased: Boolean
+
+  /** Is this symbol `lazy` */
   def isLazy: Boolean
+
+  /** Is this symbol `override` */
   def isOverride: Boolean
+
+  /** Is this symbol `inline` */
   def isInline: Boolean
-  def isMacro: Boolean                 // inline method containing toplevel splices
-  def isStatic: Boolean                // mapped to static Java member
-  def isObject: Boolean                // an object or its class (used for a ValDef or a ClassDef extends Modifier respectively)
-  def isTrait: Boolean                 // a trait (used for a ClassDef)
-  def isLocal: Boolean                 // used in conjunction with Private/private[Type] to mean private[this] extends Modifier proctected[this]
-  def isSynthetic: Boolean             // generated by Scala compiler
-  def isArtifact: Boolean              // to be tagged Java Synthetic
-  def isMutable: Boolean               // when used on a ValDef: a var
-  def isFieldAccessor: Boolean         // a getter or setter
-  def isCaseAcessor: Boolean           // getter for class parameter
-  def isCovariant: Boolean             // type parameter marked “+”
-  def isContravariant: Boolean         // type parameter marked “-”
-  def isScala2X: Boolean               // Imported from Scala2.x
-  def isDefaultParameterized: Boolean  // Method with default parameters
-  def isStable: Boolean                // Method that is assumed to be stable
+
+  /** Is this symbol markes as a macro. An inline method containing toplevel splices */
+  def isMacro: Boolean
+
+  /** Is this symbol marked as static. Mapped to static Java member */
+  def isStatic: Boolean
+
+  /** Is this symbol an object or its class (used for a ValDef or a ClassDef extends Modifier respectively) */
+  def isObject: Boolean
+
+  /** Is this symbol a trait */
+  def isTrait: Boolean
+
+  /** Is this symbol local? Used in conjunction with Private/private[Type] to mean private[this] extends Modifier proctected[this] */
+  def isLocal: Boolean
+
+  /** Was this symbol generated by Scala compiler */
+  def isSynthetic: Boolean
+
+  /** Is this symbol to be tagged Java Synthetic */
+  def isArtifact: Boolean
+
+  /** Is this symbol a `var` (when used on a ValDef) */
+  def isMutable: Boolean
+
+  /** Is this symbol a getter or a setter */
+  def isFieldAccessor: Boolean
+
+  /** Is this symbol a getter for case class parameter */
+  def isCaseAcessor: Boolean
+
+  /** Is this symbol a type parameter marked as covariant `+` */
+  def isCovariant: Boolean
+
+  /** Is this symbol a type parameter marked as contravariant `-` */
+  def isContravariant: Boolean
+
+  /** Was this symbol imported from Scala2.x */
+  def isScala2X: Boolean
+
+  /** Is this symbol a method with default parameters */
+  def isDefaultParameterized: Boolean
+
+  /** Is this symbol member that is assumed to be stable */
+  def isStable: Boolean
+
+  /** Is this symbol a parameter */
   def isParam: Boolean
+
+  /** Is this symbol a parameter accessor */
   def isParamAccessor: Boolean
 }

library/src/scala/tasty/reflect/IdOps.scala

@@ -4,6 +4,7 @@ package reflect
 trait IdOps extends Core {
 
   trait IdAPI {
+    /** Position in the source code */
     def pos(implicit ctx: Context): Position
     def name(implicit ctx: Context): String
   }

library/src/scala/tasty/reflect/PatternOps.scala

@@ -4,8 +4,10 @@ package reflect
 trait PatternOps extends Core {
 
   trait PatternAPI {
-    def tpe(implicit ctx: Context): Type
+    /** Position in the source code */
     def pos(implicit ctx: Context): Position
+
+    def tpe(implicit ctx: Context): Type
   }
   implicit def PatternDeco(pattern: Pattern): PatternAPI
 

library/src/scala/tasty/reflect/PositionOps.scala

@@ -3,15 +3,28 @@ package scala.tasty.reflect
 trait PositionOps extends Core {
 
   trait PositionAPI {
-    def start: Int
-    def end: Int
 
+    /** The path of source file */
     def sourceFile: java.nio.file.Path
 
+    /** The start index in the source file */
+    def start: Int
+
+    /** The end index in the source file */
+    def end: Int
+
+    /** The start line in the source file */
     def startLine: Int
+
+    /** The start column in the source file */
     def startColumn: Int
+
+    /** The end line in the source file */
     def endLine: Int
+
+    /** The end column in the source file */
     def endColumn: Int
+
   }
   implicit def PositionDeco(pos: Position): PositionAPI
 

library/src/scala/tasty/reflect/SettingsOps.scala

@@ -6,6 +6,7 @@ trait SettingsOps extends Core {
   def settings: Settings
 
   trait SettingsAPI {
+    /** Can print output using colors? */
     def color: Boolean
   }
   implicit def SettingsDeco(settings: Settings): SettingsAPI

library/src/scala/tasty/reflect/SignatureOps.scala

@@ -2,13 +2,17 @@ package scala.tasty.reflect
 
 trait SignatureOps extends Core {
 
+  /** Erased (JVM) signatures. */
   val Signature: SignatureExtractor
   abstract class SignatureExtractor {
+    /** Matches the erased (JVM) signature and returns its parameters and result type. */
     def unapply(sig: Signature)(implicit ctx: Context): Option[(List[String], String)]
   }
 
   trait SignatureAPI {
+    /** The (JVM) erased signatures of the parameters. */
     def paramSigs: List[String]
+    /** The (JVM) erased result type. */
     def resultSig: String
   }
   implicit def SignatureDeco(sig: Signature): SignatureAPI