scala - Scaladoc [用例]

Question

为什么 Scaladoc 中的一些方法描述以开头[use case]？

例子：scala.collection.immutable.StringOps.++

它只是将来要替换的占位符吗？

score 24 · Accepted Answer

它们是如何调用这些方法的简化示例。通常这些方法（++、map、flatMap等）包含一个隐式参数，通常是一个称为构建器工厂的参数，它（简单地说）抽象了结果集合的创建。

在大多数情况下，集合的客户端不会指定这些隐式参数，因此 ScalaDoc 允许定义方法的简化描述 -用例。这使用户能够快速了解所讨论的方法背后的想法，而不必担心例如CanBuildFrom意味着什么以及如何使用它。

例如，这是的完整声明++：

def ++[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That

在大多数情况下，目标集合类型与调用的接收者相同，因此调用看起来就像声明如下（假设++在 a 上定义，比如说，List）：

def ++(that: TraversableOnce[A]): List[A]

上面，隐式是在编译时解析的，类型参数是推断出来的。在大多数情况下，这应该是客户对方法的看法。

如果你想用用例注释你自己的方法，@usecase在你的文档注释中使用标签：

/** ...
 *  ...
 *  @usecase def ++(that: TraversableOnce[A]): List[A]
 */

1 回答 1