在文档中提及null参数的方法？

Question

我正在开发一种API，并想知道哪种方式通常更适合提及null参数：

一个。写一些像@throw NullPointerException if P is null这样的假设所有文档都没有说明它的方法将接受null-parameter：

/**
/* Does something...
/* @param p the paramteter to do something...
/* @throws NullPointerException if p is null
...

B中。写下像this parameter can be null这样的假设null参数不被接受而没有提及它：

/**
/* Does something...
/* @param p the parameter... this can be null
...

从常识来说，我觉得A更合法，但实际上写它总是很痛苦。

您会选择哪种方式？

谢谢！

Answer 1

选项A更清晰，并且具有额外的好处，即scaladoc将正确显示异常。

然而：在任何地方使用Option类型而不是null都是更好的练习和更惯用，这实际上是你没有与Java代码连接的任何地方。这样，类型系统本身将记录该参数可以省略，并且编译器将能够确保您永远不会忘记检查缺失值。

Answer 2

我认为两者都很好。你应该提一下你是否会得到一个NullPointerException。在参数可以为null的情况下，您应该描述这意味着什么，而不是仅仅说它可以为null。例如

* @param locale the Locale used to format dates, or null to use the system's default Locale.