Scaladoc [用例]

Question

为什么Scaladoc中的某些方法描述以[用例]开头？

例如：scala.collection.immutable.StringOps.++。

这只是一个占位符，以便在将来被替换吗？

- Nermin Serifovic

---

我刚刚注意到这个标签背后的原理，它在被接受的答案的评论中有所描述：https://dev59.com/E3I-5IYBdhLWcg3wsKv9#1728140 - Nermin Serifovic

Answer 1

以下是这些方法被调用的简化示例。通常这些方法（++, map, flatMap等）包含一个隐式参数，最常见的参数叫做构建器工厂，它（简单来说）抽象了结果集合的创建过程。

在大多数情况下，集合的客户端不需要指定这些隐式参数，因此ScalaDoc允许定义方法的简化描述 - 使用案例。这使得用户能够快速理解所涉及的方法的思想，而不需要关心例如CanBuildFrom的含义以及它的使用方式。

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

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

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

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

上面的代码在编译时解析隐式参数并推断类型参数。对于大多数情况下，这应该是客户端调用方法的视角。

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

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

- axel22

---

我需要一个“使用情况隐藏”按钮。 - pedrofurla

这可能是个好主意。也许你可以在Scala Trac网站上提交一个增强请求。 - axel22

我现在才注意到你是谁。所以，回答你的建议：实际上我应该自己提交它。这里是唯一参加过2010年Scaladays并当时是唯一的Scaladoc2贡献者的巴西人。很高兴收到你的来信，干杯。 - pedrofurla

是的，我知道，我一直在看到你在ScalaDoc相关的提交中。干杯！ - axel22

我想要一个非用例隐藏按钮。在大多数情况下，人们查找这些东西是为了使用它们，而不是覆盖它们。 - Hans Westerbeek