Scaladoc [用例]

Question

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

例: scala.collection.immutable.StringOps.++

它只是一个将来被替换的占位符吗？

Answer 1

它们是如何调用这些方法的简化示例.通常,这些方法(++,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]
 */