如何程序化提取Scala源码中的代码注释（兼容Scala 2.11至Scala 3）

针对你要从Scala源码中程序化提取注释，还要在Scala 2.11到Scala 3之间低维护兼容的需求，我整理了几个最优方案，按推荐优先级排序：

1. 自定义规范注释 + Scalameta轻量源码解析（最推荐，全版本兼容） #

既然你愿意按特定格式编写注释（且遵循Scaladoc规范），这个方案兼容性最好、维护成本最低——它完全不依赖编译后的字节码，只需要直接解析源码文件。

核心思路 #

用Scalameta（一个跨Scala全版本的AST解析库）读取源码，根据你约定的注释规则（比如保留标准Scaladoc，或给需要提取的注释加@extract标签）提取类/成员的注释内容，最终输出可遍历的结构（比如Map或自定义case class，转JSON也很方便）。

实现步骤 #

1. 添加Scalameta依赖（兼容Scala 2.11-3）：

   // build.sbt 示例
   libraryDependencies += "org.scalameta" %% "scalameta" % "4.9.6"
   

2. 编写解析逻辑：

   import scala.meta._
   
   // 从指定源码文件中，提取目标类的所有成员注释
   def extractClassMemberComments(sourcePath: String, targetClassName: String): Map[String, String] = {
     // 读取并解析源码为AST
     val sourceCode = scala.io.Source.fromFile(sourcePath).mkString
     val sourceAst = sourceCode.parse[Source].getOrElse(throw new IllegalArgumentException("Invalid Scala source"))
   
     // 定位目标类，提取成员注释
     sourceAst.collectFirst {
       case cls: Defn.Class if cls.name.value == targetClassName =>
         cls.members.flatMap {
           // 提取变量/方法的注释
           case m: Defn.Val if m.comment.isDefined => Some(m.name.value -> m.comment.get.text)
           case m: Defn.Def if m.comment.isDefined => Some(m.name.value -> m.comment.get.text)
           case m: Defn.Var if m.comment.isDefined => Some(m.name.value -> m.comment.get.text)
           // 支持提取类本身的注释
           case _ if cls.comment.isDefined => Some("class_self" -> cls.comment.get.text)
           case _ => None
         }.toMap
     }.getOrElse(Map.empty)
   }
   

3. 扩展优化：如果需要按全限定名查找类，可以在AST中遍历包结构，匹配完整的类路径；如果要过滤特定注释，可以在解析时检查Scaladoc标签（比如m.comment.get.tags.exists(_.name == "extract")）。

2. Scaladoc官方API适配（适合运行时通过类/实例获取） #

如果需要通过类的全限定名或实例对象来获取注释，Scaladoc的官方API是最正统的选择——它直接利用Scala编译器的注释解析能力，缺点是Scala 2和3的API有差异，需要做简单的版本适配。

核心思路 #

通过Scala的反射/编译API，拿到类的符号（Symbol），然后从符号的注释属性中提取内容。用条件编译（基于scalaVersion判断）分开编写Scala 2和3的实现，维护成本可控。

实现示例 #

Scala 2.11-2.13 版本

import scala.reflect.runtime.universe._
import scala.tools.nsc.doc.model._
import scala.tools.nsc.doc.DocFactory
import scala.tools.nsc.Settings
import scala.tools.nsc.reporters.ConsoleReporter

def getClassCommentByFQN(fullClassName: String, sourcePaths: List[String]): Option[String] = {
  val settings = new Settings()
  settings.classpath.value = sys.props("java.class.path")
  val reporter = new ConsoleReporter(settings)
  val docFactory = new DocFactory(settings, reporter)
  
  // 生成文档模型，定位目标类
  docFactory.makeUniverse(sourcePaths).flatMap { universe =>
    universe.rootPackage.findMember(fullClassName) match {
      case cls: Class => cls.comment.map(_.body) // 提取类的注释内容
      case _ => None
    }
  }
}

Scala 3 版本

import dotty.tools.dotc.doc.DocDriver
import dotty.tools.dotc.doc.model._
import dotty.tools.dotc.core.Contexts.Context
import dotty.tools.dotc.config.Settings

def getClassCommentByFQNScala3(fullClassName: String, sourcePaths: List[String]): Option[String] = {
  val settings = new Settings()
  settings.classpath.value = sys.props("java.class.path")
  given Context = (new DocDriver).createContext(settings)
  
  // 生成文档模型，定位目标类
  val universe = (new DocDriver).generateDoc(sourcePaths, settings)
  universe.rootPackage.findMember(fullClassName) match {
    case cls: Class => cls.comment.map(_.body)
    case _ => None
  }
}

适配技巧 #

在build.sbt中用条件编译加载对应版本的依赖和代码：

libraryDependencies ++= {
  if (scalaVersion.value.startsWith("2.")) {
    Seq("org.scala-lang" % "scala-compiler" % scalaVersion.value, "org.scala-lang" % "scala-reflect" % scalaVersion.value)
  } else {
    Seq("org.scala-lang" % "scala3-compiler_3" % scalaVersion.value)
  }
}

3. 编译时注解 + 宏（适合实时运行时获取） #

如果需要在运行时直接通过类实例获取注释（不需要源码文件），可以用编译时注解标记需要提取的成员，然后用宏在编译阶段把注释嵌入到字节码中，运行时直接读取。

核心思路 #

1. 定义一个标记注解，比如@ExtractComment，用来标记需要提取注释的类/成员；
2. 用Scala 2的宏或Scala 3的inline宏，在编译时提取注释内容，嵌入到代码中；
3. 运行时通过统一的API获取注释。

实现示例 #

统一注解定义

import scala.annotation.StaticAnnotation

// 标记需要提取注释的类/成员
class ExtractComment extends StaticAnnotation

Scala 2 宏实现

import scala.reflect.macros.blackbox.Context

def getCommentImpl(c: Context)(obj: c.Tree): c.Tree = {
  import c.universe._
  val sym = c.typecheck(obj).tpe.typeSymbol
  // 检查是否标记了注解，提取注释
  sym.annotations.find(_.tree.tpe =:= typeOf[ExtractComment]) match {
    case Some(_) => q"${sym.comment.map(_.body).getOrElse("")}"
    case None => q""""""
  }
}

// 对外暴露的API
def getComment(obj: Any): String = macro getCommentImpl

Scala 3 Inline宏实现

import scala.quoted._

inline def getComment(inline obj: Any): String = ${getCommentImpl('obj)}

def getCommentImpl(obj: Expr[Any])(using Quotes): Expr[String] = {
  import quotes.reflect._
  val sym = obj.asTerm.tpe.typeSymbol
  sym.annotations.find(_.tpe =:= TypeRepr.of[ExtractComment]) match {
    case Some(_) => Expr(sym.comment.getOrElse(""))
    case None => Expr("")
  }
}

方案总结 #

内容的提问来源于stack exchange，提问作者skm