api文档和“价值限制”：它们匹配吗？
您是否经常在API文档（例如“公共函数的javadoc”中）中看到“值限制”的描述以及经典文档？
注意：我不是在谈论代码中的注释
“值限制”，我的意思是：
- 参数是否可以支持空值（或空字符串，或......）？
- '返回值'可以为null或保证永远不为空（或者可以为“空”，或者......）？
样本：
我经常看到的（无法访问源代码）是：
/**
* 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文档中看到过那种信息......
编辑：
这可能会影响已检查或未检查的异常的使用与否。
你怎么看 ？值限制和API，它们是否属于同一类？
回答 2
Stack Overflow用户
发布于 2019-03-26 08:48:13
我认为他们可以属于一个整体，但不一定必须属于一起。在您的场景中，似乎有意义的是，限制以这样的方式记录，即它们出现在生成的API文档和智能感知中（如果语言/ IDE支持它）。
我认为这也取决于语言。例如，Ada具有一个“受限整数”的本机数据类型，您可以在其中定义一个整数变量，并明确指出它只会（并且始终）在某个数值范围内。在这种情况下，数据类型本身表示限制。它应该仍然可以通过API文档和intellisense查看和发现，但不是开发人员必须在注释中指定的内容。
但是，像Java和C＃这样的语言没有这种类型的受限整数，因此开发人员必须在注释中指定它，如果它是应该成为公共文档的一部分的信息。
Stack Overflow用户
发布于 2019-03-26 10:13:07
我认为那些边界条件绝对属于API。但是，我会（并经常）更进一步，并指出那些空值的含义。我指出它会抛出异常，或者我解释传递边界值时的预期结果。
很难记住总能做到这一点，但这对你班级的用户来说是件好事。如果方法呈现更改的合同（如空值被更改为不允许），那么维护它也很困难...当您更改方法的语义时，您还必须努力更新文档。
https://stackoverflow.com/questions/-100001044
复制相似问题
腾讯云开发者
