如何从 Scala API 文档中确定所需的参数？答案

【问题标题】：How to determine required parameters from Scala API documentation?如何从 Scala API 文档中确定所需的参数？
【发布时间】：2012-05-09 06:21:32
【问题描述】：

我很难解读 Scala API 文档。

例如，我定义了一个用于数据库的时间戳。

def postedDate = column[Timestamp]("posted_date", O NotNull, O Default new Timestamp(Calendar.getInstance.getTimeInMillis), O DBType("timestamp"))

如果我没有阅读几个示例，其中没有一个在 API 文档中，我该如何构造这个语句？
从 Column 文档我怎么知道参数？
我猜它与TimestampTypeMapperDelegate 有关，但仍然不清楚如何使用它。

【问题讨论】：

标签： scala scalaquery

【解决方案1】：

在 Column 的 scaladoc 中要注意的第一件事是它是抽象的，因此您可能希望直接处理它的子类。例如，命名列。

其他需要注意的是它有一个类型参数，并且构造函数接受一个相同参数类型的 TypeMapper 的隐式参数。 TypeMapper 的文档提供了一个如何创建自定义的示例，但是如果您查看子类，则会发现很多提供的子类（例如时间戳）。参数被声明为隐式这一事实表明范围内可能存在一个，如果是这样，它将自动用作参数而无需明确说明。如果没有满足要求的隐含范围，则必须提供它。

接下来要注意的是，TypeMapper 是一个特征，它使用 BasicProfile 和 TypeMapperDelegate 结果的参数扩展了一个函数。基本上这里发生的是类型映射器的定义与实现分离。这样做是为了支持多种风格的数据库。如果看一下 BasicProfile 的子类，就会发现 ScalaQuery 支持很多，而且我们知道，它们的实现有时完全不同。

如果你关注文档一段时间，你最终会发现 BasicTypeMapperDelegates 特征，其中包含一堆 val，其中包含每种基本类型（包括时间戳）的委托。

BasicTable 定义了一个名为 column 的方法（您已经找到了），并且 column 方法的目的是让您不必了解有关 TypeMappers 和 Delegates 的任何内容，只要您使用标准类型。

所以，我想回答您关于 API 文档中是否有足够信息的问题，我个人会说是的，但是可以通过更好地描述类、对象、特征和方法来增强文档。

综上所述，我一直发现利用示例、API 文档甚至项目的源代码提供了一种强大的方式来加快大多数开源项目的速度。坦率地说，其中许多项目（包括 ScalaQuery）为我节省了无数小时的工作，但可能花费了作者无数小时的个人时间来创建和提供。这些不一定是商业产品，我们作为消费者不应该将它们与我们持有的收费产品保持相同的标准。如果您发现文档不足，请贡献！

【讨论】：

感谢一个非常好的答案，很多关于脱衣前线的好技巧，真的很合适。如果我理解正确，您将描述“尽管公共 API 的内部结构”是如何工作的。我不同意你的一点是文档有足够的信息。例如，如果您查看我的默认参数时间戳，我可以在文档中的哪个位置找到它的作用？起初我以为它会自动在 date_posted 列中插入时间戳，但现在我认为它用于创建表，如果我使用进化它没用，我不会使用默认值？
我不同意你的另一件事是我们不应该让他们遵守“商业”标准。根据stackoverflow.com/questions/1362748/… Scala Query 是最成熟的 Scala 数据库框架。因此，与一些晦涩的开源爱好项目相比，应该与 JAVA Hibernate 进行更好的比较。
Scala 将在今年年底推出基于 ScalaQuery 的集成查询抽象。从它的外观来看，它会比 Java 的最新技术要好得多。
@Farmor Hibernate 支持 Red Hat。
我很高兴你发现这个答案很有用，我也理解你的痛苦。在 API 指南中，Default 是 ColumnOptions 的子类。如果您考虑作为 ColumnOptions 子类的其他事物（AutoInc、DBType、NotNull、Nullable、PrimaryKey），您将希望得出 Default 允许您为列定义默认值的结论。文档在这里：scalaquery.org/doc/api/scalaquery-0.9.4/…。不幸的是，Default 是 Object 的成员，在 ScalaDoc 界面中不可搜索。