scala - 为什么 Scaladoc 方法签名是错误的？

Question

Scala API里面有很多地方，尤其是在方法签名错误的集合中。

例如，Map 的 scaladoc 签名. flatMap说

def flatMap[B](f: (A) ⇒ GenTraversableOnce[B]): Map[B]

但实际签名是

flatMap[B, That](f: ((A, B)) ⇒ GenTraversableOnce[B])
    (implicit bf: CanBuildFrom[Map[A, B], B, That]): That

这个特别没有意义，因为 scaladoc 签名包括 Map[B] ，但是 Map有两个类型参数，不是一个。

这里发生了什么？这是一个错误吗？

Answer 1

您在生成的文档中看到的错误签名称为“用例”。他们应该通过展示理想化的 API 来澄清文档，类似于真实的 API，但省略了繁琐的细节(比如普遍存在的隐式 CanBuildFrom 参数 bothers some people)。

对于具有用例的方法，您可以通过单击方法名称以显示该方法的详细信息，然后单击“完整签名”以展开显示签名的另一部分来获取真实签名。

引用

Scala issue SI-3448 ，创建于 2010 年 5 月，专门处理为 Map 显示的错误数量的类型参数.此问题已于 2012 年 7 月关闭“不会修复”。

保罗·菲利普斯的演讲 Scala Collections: Why Not?从 2014 年 1 月开始，在 slide 1 中 mock 用例为“谎言” , slide 2 , slide 3 .

在 GenTraversableLike.scala您可以看到导致生成用例文档的指令示例:

@usecase def flatMap[B](f: A => TraversableOnce[B]): $Coll[B]

类似问题

Why does the scaladoc say HashMap.toArray returns Array[A] instead of Array[(A,B)]?

The List :: method and covariance ... why do they hide the real signature?

scaladoc for map on Map ... is the documentation wrong, or am I missing something?

What's going on here with scala.collection.immutable.Stack.+: (prepend)? ...

Why do some method descriptions in Scaladoc start with [use case]?

How to explain Map.map result