Scala3执行sbt doc时继承Iterator[_]触发AssertionError

问题现象 #

• 代码运行完全正常，但执行 sbt doc 生成API文档时会抛出 AssertionError
• 仅在继承 Iterator[Bar] 时触发，换成 Iterable[Bar] 等其他父类则无此问题

复现代码 #

trait Bar

object Foo extends Iterator[Bar]:
  override def hasNext: Boolean = ???
  override def next(): Bar      = ???

异常栈关键片段 #

[info] welcome to sbt 1.7.1 (Oracle Corporation Java 17.0.1)
[info] loading global plugins from ...\.sbt\1.0\plugins
[info] loading project definition from ...\docfailexample\project
[info] loading settings for project root from build.sbt ...
[info] set current project to docfailexample (in build file:/.../docfailexample/)
[success] Total time: 0 s, completed 5 Nov 2022, 2:50:24 pm
[info] compiling 1 Scala source to ...\docfailexample\target\scala-3.2.0\classes ...
[info] Main Scala API documentation to ...\docfailexample\target\scala-3.2.0\api...
[info] Skipping unused scalacOptions: -Werror
Problem parsing src\main\scala\Main.scala:<0..124>, documentation may not be generated.
java.lang.AssertionError: assertion failed
  | => rat scala.runtime.Scala3RunTime$.assertFailed(Scala3RunTime.scala:11)
        at dotty.tools.dotc.util.Spans$Span$.start$extension(Spans.scala:45)
        at dotty.tools.dotc.util.SourcePosition.start(SourcePosition.scala:52)
        at scala.quoted.runtime.impl.QuotesImpl$reflect$PositionMethods$.start(QuotesImpl.scala:2813)
        at scala.quoted.runtime.impl.QuotesImpl$reflect$PositionMethods$.start(QuotesImpl.scala:2813)
        at dotty.tools.scaladoc.tasty.ClassLikeSupport.getParentsAsTreeSymbolTuples$$anonfun$1(ClassLikeSupport.scala:260)
        at scala.collection.Iterator$$anon$6.hasNext(Iterator.scala:472)
        at scala.collection.Iterator$$anon$9.hasNext(Iterator.scala:576)
        at scala.collection.immutable.List.prependedAll(List.scala:152)
        at scala.collection.immutable.List$.from(List.scala:684)
        at scala.collection.immutable.List$.from(List.scala:681)
        at scala.collection.IterableOps$WithFilter.map(Iterable.scala:891)

排查思路与见解 #

1. 根源定位：从栈帧可以看出，问题出在Scaladoc的tasty.ClassLikeSupport模块处理父类符号与语法树的映射时，断言失败。这说明Scaladoc在解析Iterator相关的继承关系时，对源码位置的处理存在逻辑漏洞。
2. 临时规避方案：
   • 若必须生成文档，可先临时替换父类为Iterable[Bar]，生成文档后再改回；
   • 尝试升级Scala 3版本（比如从3.2.0升级到更高版本），这类工具链的bug通常会在后续版本中修复；
   • 临时跳过Iterator相关类的文档生成，或用@hideInDocument注解标记该对象。
3. 长期处理：这是Scaladoc工具链的bug，可在Scala官方仓库提交issue，附上复现代码和异常栈，帮助官方修复问题。

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