api文档和"价值限制":它们匹配吗？

Question

您是否经常在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,它们是否属于一起？

Answer 1

我认为他们可以属于一个整体,但不一定必须属于一起.在您的场景中,似乎有意义的是,限制以这样的方式记录,即它们出现在生成的API文档和智能感知中(如果语言/ IDE支持它).

我认为这也取决于语言.例如,Ada具有一个"受限整数"的本机数据类型,您可以在其中定义一个整数变量,并明确指出它只会(并且始终)在某个数值范围内.在这种情况下,数据类型本身表示限制.它应该仍然可以通过API文档和intellisense查看和发现,但不是开发人员必须在注释中指定的内容.

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