Merge pull request #9858 from dotty-staging/rename-Reflection-Comment-to-Documentation

Rename reflection comment to documentation

Author: abgruszecki

compiler/src/dotty/tools/dotc/quoted/QuoteContextImpl.scala

@@ -2233,11 +2233,11 @@ class QuoteContextImpl private (ctx: Context) extends QuoteContext:
 
         def localContext: Context =
           if self.exists then ctx.withOwner(self) else ctx
-        def comment: Option[Comment] =
+        def documentation: Option[Documentation] =
           import dotc.core.Comments.CommentsContext
           val docCtx = ctx.docCtx.getOrElse {
             throw new RuntimeException(
-              "DocCtx could not be found and comments are unavailable. This is a compiler-internal error."
+              "DocCtx could not be found and documentations are unavailable. This is a compiler-internal error."
             )
           }
           docCtx.docstring(self)
@@ -2520,18 +2520,18 @@ class QuoteContextImpl private (ctx: Context) extends QuoteContext:
     def warning(msg: => String, sourceFile: SourceFile, start: Int, end: Int): Unit =
       dotc.report.error(msg, dotc.util.SourcePosition(sourceFile, dotc.util.Spans.Span(start, end)))
 
-    type Comment = dotc.core.Comments.Comment
+    type Documentation = dotc.core.Comments.Comment
 
-    object Comment extends CommentModule
+    object Documentation extends DocumentationModule
 
-    object CommentMethodsImpl extends CommentMethods:
-      extension (self: Comment):
+    object DocumentationMethodsImpl extends DocumentationMethods:
+      extension (self: Documentation):
         def raw: String = self.raw
         def expanded: Option[String] = self.expanded
         def usecases: List[(String, Option[DefDef])] =
           self.usecases.map { uc => (uc.code, uc.tpdCode) }
       end extension
-    end CommentMethodsImpl
+    end DocumentationMethodsImpl
 
     private def optional[T <: dotc.ast.Trees.Tree[?]](tree: T): Option[tree.type] =
       if tree.isEmpty then None else Some(tree)

library/src/scala/tasty/Reflection.scala

@@ -105,7 +105,7 @@ import scala.tasty.reflect._
  *
  *  +- Position
  *
- *  +- Comment
+ *  +- Documentation
  *
  *  +- Constant
  *
@@ -2551,8 +2551,8 @@ trait Reflection { reflection =>
 
       def localContext: Context
 
-      /** The comment for this symbol, if any */
-      def comment: Option[Comment]
+      /** The documentation for this symbol, if any */
+      def documentation: Option[Documentation]
 
       /** Tree of this definition
         *
@@ -3138,28 +3138,26 @@ trait Reflection { reflection =>
   /** Emits a warning at a specific range of a file */
   def warning(msg: => String, source: SourceFile, start: Int, end: Int): Unit
 
-  //////////////
-  // COMMENTS //
-  //////////////
-
-  // TODO: misnomer. Rename to `Documentation`
+  ///////////////////
+  // DOCUMENTATION //
+  ///////////////////
 
   /** Attachment representing the documentation of a definition */
-  type Comment <: AnyRef
+  type Documentation <: AnyRef
 
-  val Comment: CommentModule
+  val Documentation: DocumentationModule
 
-  trait CommentModule { this: Comment.type => }
+  trait DocumentationModule { this: Documentation.type => }
 
-  given CommentMethods as CommentMethods = CommentMethodsImpl
-  protected val CommentMethodsImpl: CommentMethods
+  given DocumentationMethods as DocumentationMethods = DocumentationMethodsImpl
+  protected val DocumentationMethodsImpl: DocumentationMethods
 
-  trait CommentMethods {
-    extension (self: Comment):
-      /** Raw comment string */
+  trait DocumentationMethods {
+    extension (self: Documentation):
+      /** Raw documentation string */
       def raw: String
 
-      /** Expanded comment string, if any */
+      /** Expanded documentation string, if any */
       def expanded: Option[String]
 
       /** List of usecases and their corresponding trees, if any */

tastydoc/src/dotty/tastydoc/TastyExtractor.scala

@@ -39,7 +39,7 @@ trait TastyExtractor extends TastyTypeConverter with CommentParser with CommentC
     })
   }
 
-  def extractComments(using QuoteContext)(comment: Option[qctx.tasty.Comment], rep: Representation) : (Map[String, EmulatedPackageRepresentation], String) => Option[Comment] = {
+  def extractComments(using QuoteContext)(comment: Option[qctx.tasty.Documentation], rep: Representation) : (Map[String, EmulatedPackageRepresentation], String) => Option[Comment] = {
     comment match {
       case Some(com) =>
         (packages, userDocSyntax) => {

tastydoc/src/dotty/tastydoc/representations.scala

@@ -89,7 +89,7 @@ object representations extends TastyExtractor {
     override val members = internal.stats.map(convertToRepresentation(_, Some(this)))
     override val annotations = extractAnnotations(internal.symbol.annots)
 
-    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.comment, this)(packages, userDocSyntax)
+    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.documentation, this)(packages, userDocSyntax)
   }
 
   class ImportRepresentation(using QuoteContext)(internal: qctx.tasty.Import, override val parentRepresentation: Option[Representation])(using mutablePackagesMap: scala.collection.mutable.HashMap[String, EmulatedPackageRepresentation]) extends Representation {
@@ -103,7 +103,7 @@ object representations extends TastyExtractor {
     override val path = internal.expr.symbol.show.split("\\.").toList
     override val annotations = extractAnnotations(internal.symbol.annots)
 
-    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.comment, this)(packages, userDocSyntax)
+    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.documentation, this)(packages, userDocSyntax)
   }
 
   class ClassRepresentation(using QuoteContext)(internal: qctx.tasty.ClassDef, override val parentRepresentation: Option[Representation])(using mutablePackagesMap: scala.collection.mutable.HashMap[String, EmulatedPackageRepresentation]) extends Representation with Members with Parents with Modifiers with Companion with Constructors with TypeParams {
@@ -139,7 +139,7 @@ object representations extends TastyExtractor {
     )
     override val members: List[Representation with Modifiers] = extractClassMembers(internal.body, internal.symbol, Some(this))
 
-    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.comment, this)(packages, userDocSyntax)
+    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.documentation, this)(packages, userDocSyntax)
   }
 
   class DefRepresentation(using QuoteContext)(internal: qctx.tasty.DefDef, override val parentRepresentation: Option[Representation])(using mutablePackagesMap: scala.collection.mutable.HashMap[String, EmulatedPackageRepresentation]) extends Representation with Modifiers with TypeParams with MultipleParamList with ReturnValue {
@@ -158,7 +158,7 @@ object representations extends TastyExtractor {
     }
     override val returnValue = convertTypeToReference(internal.returnTpt.tpe)
     override val annotations = extractAnnotations(internal.symbol.annots)
-    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.comment, this)(packages, userDocSyntax)
+    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.documentation, this)(packages, userDocSyntax)
   }
 
   class ValRepresentation(using QuoteContext)(internal: qctx.tasty.ValDef, override val parentRepresentation: Option[Representation])(using mutablePackagesMap: scala.collection.mutable.HashMap[String, EmulatedPackageRepresentation]) extends Representation with Modifiers with ReturnValue {
@@ -171,7 +171,7 @@ object representations extends TastyExtractor {
     override val annotations = extractAnnotations(internal.symbol.annots)
     val isVar: Boolean = internal.symbol.flags.is(Flags.Mutable)
 
-    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.comment, this)(packages, userDocSyntax)
+    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.documentation, this)(packages, userDocSyntax)
   }
 
   class TypeRepresentation(using QuoteContext)(internal: qctx.tasty.TypeDef, override val parentRepresentation: Option[Representation])(using mutablePackagesMap: scala.collection.mutable.HashMap[String, EmulatedPackageRepresentation]) extends Representation with Modifiers with TypeParams {
@@ -188,7 +188,7 @@ object representations extends TastyExtractor {
       case _ => None
     }
     override def isAbstract: Boolean = !alias.isDefined
-    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.comment, this)(packages, userDocSyntax)
+    override def comments(packages: Map[String, EmulatedPackageRepresentation], userDocSyntax: String) = extractComments(internal.symbol.documentation, this)(packages, userDocSyntax)
   }
 
   def convertToRepresentation(using QuoteContext)(tree: qctx.tasty.Tree, parentRepresentation: Option[Representation])(using mutablePackagesMap: scala.collection.mutable.HashMap[String, EmulatedPackageRepresentation]): Representation = {

tests/run-custom-args/tasty-inspector/tasty-comment-inspector/Foo.scala renamed to tests/run-custom-args/tasty-inspector/tasty-documentation-inspector/Foo.scala

@@ -3,20 +3,20 @@ import scala.tasty.inspector._
 
 object Test {
   def main(args: Array[String]): Unit = {
-    new CommentInspector().inspect("", List("Foo"))
+    new DocumentationInspector().inspect("", List("Foo"))
   }
 }
 
-class CommentInspector extends TastyInspector {
+class DocumentationInspector extends TastyInspector {
 
   protected def processCompilationUnit(using QuoteContext)(root: qctx.tasty.Tree): Unit = {
     import qctx.tasty._
     object Traverser extends TreeTraverser {
 
       override def traverseTree(tree: Tree)(implicit ctx: Context): Unit = tree match {
         case tree: Definition =>
-          tree.symbol.comment match {
-            case Some(com) => println(com.raw)
+          tree.symbol.documentation match {
+            case Some(doc) => println(doc.raw)
             case None => println()
           }
           super.traverseTree(tree)