为什么 Scaladoc 方法签名是错误的? [英] Why are scaladoc method signatures wrong?
问题描述
Scala API 中有很多地方，特别是在集合中，方法签名是错误的.
There are a lot of places in the Scala API, particularly in collections, where method signatures are wrong.
例如，Map的 scaladoc 签名.flatMap 说
For example, the scaladoc signature for Map.flatMap says
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有两个类型参数，而不是一个.
This one especially makes no sense because the scaladoc signature includes Map[B], but Map has two type parameters, not one.
这是怎么回事?这是一个错误吗?
What's going on here? Is this a mistake?
推荐答案
您在生成的文档中看到的错误签名称为用例".他们应该通过展示理想化的 API 来澄清文档，类似于真实的 API，但省略了繁琐的细节(比如普遍存在的隐式 CanBuildFrom 参数，其中 困扰一些人).
The incorrect signatures you're see in the generated documentation are called "use cases". They're supposed to clarify the documentation by showing idealized API, similar to the real one but omitting tedious details (like the pervasive implicit CanBuildFrom parameter which bothers some people).
对于具有用例的方法，您可以通过单击方法名称以显示该方法的详细信息，然后单击完整签名"以展开显示签名的另一部分来获取真实签名.
For methods with use cases, you can get to the real signature by clicking the method name to show the details for that method, and then clicking "Full Signature" to expand another section that shows the signature.
Scala 问题 SI-3448，创建于 2010 年 5 月，专门处理错误的数字为
Map显示的类型参数.此问题已于 2012 年 7 月无法修复".
Scala issue SI-3448, created May 2010, deals specifically with the wrong number of type parameters being shown for
Map. This issue as closed "Won't Fix" in July 2012.
Paul Phillips 的演讲 Scala Collections:为什么不? 从 2014 年 1 月开始，在 幻灯片 1 中将用例视为谎言"，幻灯片 2、幻灯片 3.
Paul Phillips' talk Scala Collections: Why Not? from January 2014 scorns the use cases as "lies" in slide 1, slide 2, slide 3.
在 GenTraversableLike.scala 您可以看到导致生成用例文档的指令示例:
In GenTraversableLike.scala you can see an example of a directive which causes use case documentation to be generated:
@usecase def flatMap[B](f: A => TraversableOnce[B]): $Coll[B]
- 为什么scaladoc 说 HashMap.toArray 返回 Array[A] 而不是 Array[(A,B)]?
- List :: 方法和协方差......为什么它们隐藏真正的签名?
- scaladoc 用于地图上的地图...是文档错误，还是我遗漏了什么?
- scala.collection 发生了什么.immutable.Stack.+: (前置)?...
- 为什么 Scaladoc 中的一些方法描述以 [use case] 开头?
- 如何解释 Map.map 结果
这篇关于为什么 Scaladoc 方法签名是错误的?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
