我们经常在API文档中(例如在"公共函数的javadoc"中)看到"值限制"的描述以及经典文档吗？

注意：我不是在谈论代码中的注释

所谓"价值限制"，是指：

• 参数是否可以支持null值(或者空String或者...)？
• "返回值"是否可以为null或者保证永远不为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，它们是否属于同一类？

解决方案

回答

我认为它们确实如此，并且始终将注释注释地放在头文件(c ++)中。

除了有效的输入/输出/返回注释之外，我还注意到该函数很可能引发哪些异常(由于我经常想将返回值用于...很好地返回一个值，所以我更喜欢异常而不是错误代码)

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

回答

我认为这些边界条件绝对属于API。但是，我会(而且经常这样做)走得更远，并指出这些空值的含义。我或者表明它将抛出异常，或者我解释了传递边界值时的预期结果。

很难记住总是这样做，但这对班级用户来说是一件好事。如果方法的约定发生变化(例如，将空值更改为不允许)，也很难维护它。。。在更改方法的语义时，还必须勤奋地更新文档。

回答

我认为它们可以在一起，但不一定必须在一起。在方案中，将限制记录在生成的API文档和智能提示(如果语言/ IDE支持)中似乎是有意义的。

我认为这也取决于语言。例如，Ada的本机数据类型是"受限整数"，我们可以在其中定义一个整数变量，并明确指示该变量将(始终)位于某个数值范围内。在这种情况下，数据类型本身会指示限制。通过API文档和智能感知，它仍然应该是可见和可发现的，但是开发人员不必在注释中指定它。

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

回答

@Fire Lancer：对！我忘记了异常，但是我希望看到它们被提及，尤其是此公共方法可能引发的未经检查的"运行时"异常

@迈克·斯通：

you have to be diligent also to update the docs when you change the semantics of the method.

嗯，我当然希望，只要发生影响功能约定的更改，就至少要更新公共API文档。如果没有，这些API文档可能会完全删除。

为了让想法更加有趣(并使用@Scott Dorman)，我偶然发现了Java7注释的未来

那是什么意思？某些"边界条件"(而不是文档中的内容)应该更好地存在于API本身中，并在编译时与适当的"断言"生成的代码自动使用。

这样，如果API中有一个'@CheckForNull'，该函数的编写者可能甚至不编写文档就摆脱了！而且，如果语义发生变化，其API将反映出这种变化(例如"不再有@CheckForNull")

这种方法表明，对于"边界条件"进行记录是一种额外的奖励，而不是强制性的做法。

但是，这并不涵盖函数的返回对象的特殊值。为此，仍然需要完整的文档。