From 70d58393a5102f427c822a8dfb57264a9136fdca Mon Sep 17 00:00:00 2001 From: Nicolas Stucki Date: Mon, 12 Nov 2018 14:14:32 +0100 Subject: [PATCH 1/2] Add documentation to TASTy reflect --- library/src/scala/tasty/reflect/Core.scala | 78 ++++++++++++++++- library/src/scala/tasty/reflect/FlagSet.scala | 84 +++++++++++++++---- library/src/scala/tasty/reflect/IdOps.scala | 1 + .../src/scala/tasty/reflect/PatternOps.scala | 4 +- .../src/scala/tasty/reflect/PositionOps.scala | 17 +++- .../src/scala/tasty/reflect/SettingsOps.scala | 1 + .../scala/tasty/reflect/SignatureOps.scala | 4 + .../src/scala/tasty/reflect/SymbolOps.scala | 28 ++++++- library/src/scala/tasty/reflect/TreeOps.scala | 2 + .../tasty/reflect/TypeOrBoundsTreeOps.scala | 2 + 10 files changed, 199 insertions(+), 22 deletions(-) diff --git a/library/src/scala/tasty/reflect/Core.scala b/library/src/scala/tasty/reflect/Core.scala index edf0823cc35a..e8dd584488ea 100644 --- a/library/src/scala/tasty/reflect/Core.scala +++ b/library/src/scala/tasty/reflect/Core.scala @@ -126,17 +126,40 @@ trait Core { /** Tree representing executable 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 } diff --git a/library/src/scala/tasty/reflect/FlagSet.scala b/library/src/scala/tasty/reflect/FlagSet.scala index 860c51bdb290..1c9ad1d284e0 100644 --- a/library/src/scala/tasty/reflect/FlagSet.scala +++ b/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 } diff --git a/library/src/scala/tasty/reflect/IdOps.scala b/library/src/scala/tasty/reflect/IdOps.scala index bcfe095fd701..389cde6e4679 100644 --- a/library/src/scala/tasty/reflect/IdOps.scala +++ b/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 } diff --git a/library/src/scala/tasty/reflect/PatternOps.scala b/library/src/scala/tasty/reflect/PatternOps.scala index ede392d9bc15..0bc54fd455e3 100644 --- a/library/src/scala/tasty/reflect/PatternOps.scala +++ b/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 diff --git a/library/src/scala/tasty/reflect/PositionOps.scala b/library/src/scala/tasty/reflect/PositionOps.scala index c8a2dd1a82cd..7b5d677f109d 100644 --- a/library/src/scala/tasty/reflect/PositionOps.scala +++ b/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 diff --git a/library/src/scala/tasty/reflect/SettingsOps.scala b/library/src/scala/tasty/reflect/SettingsOps.scala index 002072feaa46..021fa4bb7f3a 100644 --- a/library/src/scala/tasty/reflect/SettingsOps.scala +++ b/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 diff --git a/library/src/scala/tasty/reflect/SignatureOps.scala b/library/src/scala/tasty/reflect/SignatureOps.scala index d06047775094..8c664f204807 100644 --- a/library/src/scala/tasty/reflect/SignatureOps.scala +++ b/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 diff --git a/library/src/scala/tasty/reflect/SymbolOps.scala b/library/src/scala/tasty/reflect/SymbolOps.scala index 163a62199c10..b49a8b550017 100644 --- a/library/src/scala/tasty/reflect/SymbolOps.scala +++ b/library/src/scala/tasty/reflect/SymbolOps.scala @@ -8,28 +8,46 @@ trait SymbolOps extends Core { trait SymbolAPI { + /** Owner of this symbol. The owner is the symbol in which this symbol is defined. */ def owner(implicit ctx: Context): Symbol + /** Flags of this symbol */ def flags(implicit ctx: Context): FlagSet + /** This symbol is private within the resulting type. */ def privateWithin(implicit ctx: Context): Option[Type] + + /** This symbol is protected within the resulting type. */ def protectedWithin(implicit ctx: Context): Option[Type] - /** Name of the definition */ + /** The name of this symbol. */ def name(implicit ctx: Context): String - /** Full name of the definition from the _root_ package */ + /** The full name of this symbol up to the root package. */ def fullName(implicit ctx: Context): String + /** Returns the context within this symbol. */ def localContext(implicit ctx: Context): Context + /** Unsafe cast as to PackageSymbol. Use IsPackageSymbol to safly check and cast to PackageSymbol */ def asPackage(implicit ctx: Context): PackageSymbol + + /** Unsafe cast as to ClassSymbol. Use IsClassSymbol to safly check and cast to ClassSymbol */ def asClass(implicit ctx: Context): ClassSymbol + + /** Unsafe cast as to DefSymbol. Use IsDefSymbol to safly check and cast to DefSymbol */ def asDef(implicit ctx: Context): DefSymbol + + /** Unsafe cast as to ValSymbol. Use IsValSymbol to safly check and cast to ValSymbol */ def asVal(implicit ctx: Context): ValSymbol + + /** Unsafe cast as to TypeSymbol. Use IsTypeSymbol to safly check and cast to TypeSymbol */ def asType(implicit ctx: Context): TypeSymbol + + /** Unsafe cast as to BindSymbol. Use IsBindSymbol to safly check and cast to BindSymbol */ def asBind(implicit ctx: Context): BindSymbol + /** Annotations attached to this symbol */ def annots(implicit ctx: Context): List[Term] } @@ -61,7 +79,7 @@ trait SymbolOps extends Core { } trait ClassSymbolAPI { - /** Tree of this class definition */ + /** ClassDef tree of this defintion. */ def tree(implicit ctx: Context): ClassDef /** Fields directly declared in the class */ @@ -102,6 +120,7 @@ trait SymbolOps extends Core { } trait TypeSymbolAPI { + /** TypeDef tree of this defintion. */ def tree(implicit ctx: Context): TypeDef } implicit def TypeSymbolDeco(symbol: TypeSymbol): TypeSymbolAPI @@ -114,6 +133,7 @@ trait SymbolOps extends Core { } trait DefSymbolAPI { + /** DefDef tree of this defintion. */ def tree(implicit ctx: Context): DefDef } implicit def DefSymbolDeco(symbol: DefSymbol): DefSymbolAPI @@ -126,6 +146,7 @@ trait SymbolOps extends Core { } trait ValSymbolAPI { + /** ValDef tree of this defintion. */ def tree(implicit ctx: Context): ValDef /** The class symbol of the companion module class */ @@ -142,6 +163,7 @@ trait SymbolOps extends Core { } trait BindSymbolAPI { + /** Bind pattern of this defintion. */ def tree(implicit ctx: Context): Bind } implicit def BindSymbolDeco(symbol: BindSymbol): BindSymbolAPI diff --git a/library/src/scala/tasty/reflect/TreeOps.scala b/library/src/scala/tasty/reflect/TreeOps.scala index 471d9bdd3d7d..8da1eaefda26 100644 --- a/library/src/scala/tasty/reflect/TreeOps.scala +++ b/library/src/scala/tasty/reflect/TreeOps.scala @@ -4,7 +4,9 @@ package reflect trait TreeOps extends Core { trait TreeAPI { + /** Position in the source code */ def pos(implicit ctx: Context): Position + def symbol(implicit ctx: Context): Symbol } implicit def TreeDeco(tree: Tree): TreeAPI diff --git a/library/src/scala/tasty/reflect/TypeOrBoundsTreeOps.scala b/library/src/scala/tasty/reflect/TypeOrBoundsTreeOps.scala index 2a772e2ad5f2..e783548c5526 100644 --- a/library/src/scala/tasty/reflect/TypeOrBoundsTreeOps.scala +++ b/library/src/scala/tasty/reflect/TypeOrBoundsTreeOps.scala @@ -11,7 +11,9 @@ trait TypeOrBoundsTreeOps extends Core { // ----- TypeTrees ------------------------------------------------ trait TypeTreeAPI { + /** Position in the source code */ def pos(implicit ctx: Context): Position + def tpe(implicit ctx: Context): Type def symbol(implicit ctx: Context): Symbol } From e3b9aa2598bcf4dfb187e358188a4b45a8c3f063 Mon Sep 17 00:00:00 2001 From: Nicolas Stucki Date: Wed, 14 Nov 2018 14:56:42 +0100 Subject: [PATCH 2/2] Adresse comments --- library/src/scala/tasty/reflect/Core.scala | 2 +- library/src/scala/tasty/reflect/FlagSet.scala | 44 +++++++++---------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/library/src/scala/tasty/reflect/Core.scala b/library/src/scala/tasty/reflect/Core.scala index e8dd584488ea..843e7f7bd707 100644 --- a/library/src/scala/tasty/reflect/Core.scala +++ b/library/src/scala/tasty/reflect/Core.scala @@ -124,7 +124,7 @@ 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 */ diff --git a/library/src/scala/tasty/reflect/FlagSet.scala b/library/src/scala/tasty/reflect/FlagSet.scala index 1c9ad1d284e0..4b035ade47a5 100644 --- a/library/src/scala/tasty/reflect/FlagSet.scala +++ b/library/src/scala/tasty/reflect/FlagSet.scala @@ -14,72 +14,72 @@ trait FlagSet { /** Is this symbol `sealed` */ def isSealed: Boolean - /** Is this symbol `case`. */ + /** Is this symbol `case` */ def isCase: Boolean - /** Is this symbol `implicit`. */ + /** Is this symbol `implicit` */ def isImplicit: Boolean - /** Is this symbol `erased`. */ + /** Is this symbol `erased` */ def isErased: Boolean - /** Is this symbol `lazy`. */ + /** Is this symbol `lazy` */ def isLazy: Boolean - /** Is this symbol `override`. */ + /** Is this symbol `override` */ def isOverride: Boolean - /** Is this symbol `inline`. */ + /** Is this symbol `inline` */ def isInline: Boolean - /** Is this symbol markes as a macro. An inline method containing toplevel splices. */ + /** 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. */ + /** 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. */ + /** 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]. */ + /** 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. */ + /** Was this symbol generated by Scala compiler */ def isSynthetic: Boolean - /** Is this symbol to be tagged Java Synthetic. */ + /** Is this symbol to be tagged Java Synthetic */ def isArtifact: Boolean - /** Is this symbol a `var` (when used on a ValDef). */ + /** Is this symbol a `var` (when used on a ValDef) */ def isMutable: Boolean - /** Is this symbol a getter or a setter. */ + /** Is this symbol a getter or a setter */ def isFieldAccessor: Boolean - /** Is this symbol a getter for case class parameter. */ + /** Is this symbol a getter for case class parameter */ def isCaseAcessor: Boolean - /** Is this symbol a type parameter marked as covariant `+`. */ + /** Is this symbol a type parameter marked as covariant `+` */ def isCovariant: Boolean - /** Is this symbol a type parameter marked as contravariant `-`. */ + /** Is this symbol a type parameter marked as contravariant `-` */ def isContravariant: Boolean - /** Was this symbol imported from Scala2.x. */ + /** Was this symbol imported from Scala2.x */ def isScala2X: Boolean - /** Is this symbol a method with default parameters. */ + /** Is this symbol a method with default parameters */ def isDefaultParameterized: Boolean - /** Is this symbol member that is assumed to be stable. */ + /** Is this symbol member that is assumed to be stable */ def isStable: Boolean - /** Is this symbol a parameter. */ + /** Is this symbol a parameter */ def isParam: Boolean - /** Is this symbol a parameter accessor. */ + /** Is this symbol a parameter accessor */ def isParamAccessor: Boolean }