language-agnostic - api 文档和 "value limits": do they match?

Question

您是否经常在 API 文档(例如“公共(public)函数的 javadoc”)中看到“值限制”的描述以及经典文档？

注:我不是在谈论comments within the code

通过“值(value)限制”，我的意思是:

参数是否可以支持空值(或空字符串，或...)？

'返回值'可以为空还是保证永远不会为空(或者可以是“空”，或者......)？

sample :

我经常看到的(无法访问源代码)是:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

我希望看到的是:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

我的观点是:

当我使用带有 getReaderNames() 函数的库时，我通常甚至不需要阅读 API 文档来猜测它的作用。但我需要确定如何使用它。

当我想使用这个函数时，我唯一关心的是:在参数和返回值方面我应该期待什么？这就是我安全设置参数和安全测试返回值所需要知道的全部内容，但我几乎从未在 API 文档中看到此类信息......

编辑:

这会影响 checked or unchecked exceptions 的使用与否.

你怎么看 ？值限制和 API，它们是否属于一起？

Answer 1

我认为他们 可以属于一起但不一定有属于一起。在您的场景中，似乎有必要将限制记录在生成的 API 文档和智能感知中(如果语言/IDE 支持它)。

我认为这也取决于语言。例如，Ada 有一个“受限整数”的 native 数据类型，您可以在其中定义一个整数变量并明确指出它只会(并且总是)在某个数字范围内。在这种情况下，数据类型本身表明了限制。它仍然应该通过 API 文档和智能感知可见和可发现，但开发人员不必在评论中指定。

然而，像 Java 和 C# 这样的语言没有这种类型的受限整数，因此如果它是应该成为公共(public)文档一部分的信息，开发人员必须在注释中指定它。