Language agnostic api文档和；“值限制”：他们匹配吗？

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

注意：我不是说

所谓“价值限制”，我的意思是：

• 参数是否支持空值（或空字符串，或…）
• “返回值”是否可以为null或保证永远不会为null（或可以为“空”，或…？）

示例：

我经常看到（没有源代码）是：

/**
*获取此当前报表的所有读卡器名称

*警告报告一定是先发表的。
*@param aReaderNameRegexp筛选器，以便仅返回与regexp匹配的读取器
*@return读取器名称数组
*/
字符串[]getReaderNames（最终字符串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);

/**
*获取此当前报表的所有读卡器名称

*警告报告一定是先发表的。
*@param aReaderNameRegexp筛选器，以便仅返回与regexp匹配的读取器
*（可以为null或空）
*@return读取器名称数组
*（如果报告尚未发布，则为空，
*如果没有读卡器匹配条件，则为空数组，
*读卡器名称（与regexp匹配的数组，如果regexp为null或空，则为所有读卡器）
*/
字符串[]getReaderNames（最终字符串aReaderNameRegexp）；

我的观点是：

当我使用一个包含getReaderNames（）函数的库时，我通常甚至不需要阅读API文档来猜测它的功能。但我需要确定如何使用它

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

编辑：

这可能会影响使用，也可能不会影响

---

你觉得怎么样？值限制和API，它们是否属于同一类？

我认为它们属于同一类，并且总是在头文件（c++）中添加注释

除了有效的输入/输出/返回注释外，我还注意到函数可能会抛出哪些异常（因为我经常希望使用返回值来…返回值，我更喜欢异常而不是错误代码）

---

我认为这些边界条件绝对属于API。然而，我会（并且经常会）更进一步，指出那些空值的含义。我要么指出它将抛出异常，要么解释传入边界值时的预期结果

---

很难记住总是这样做，但这对类用户来说是件好事。如果该方法的契约出现更改（如将空值更改为不允许），则维护它也很困难。。。当您更改方法的语义时，您还必须努力更新文档。

我认为它们可以属于一起，但不一定属于一起。在您的场景中，将限制记录在生成的API文档和intellisense（如果语言/IDE支持）中似乎是有意义的

我认为这也取决于语言。例如，Ada有一个本机数据类型，它是一个“受限整数”，您可以定义一个整数变量，并明确指出它将仅（并且始终）在某个数值范围内。在这种情况下，数据类型本身表示限制。它应该仍然可以通过API文档和intellisense看到和发现，但开发人员不必在注释中指定

---

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

@Fire Lancer:对！我忘记了异常，但我希望看到提到它们，特别是这个公共方法可能抛出的未经检查的“运行时”异常

@迈克·斯通：

当您更改方法的语义时，还必须努力更新文档

嗯，我当然希望公共API文档至少在发生影响函数契约的更改时更新。否则，这些API文档可能会全部删除

为了给你的想法添加食物（和@Scott Dorman一起），我只是偶然发现

这意味着什么？某些“边界条件”，而不是在文档中，应该在API本身中得到更好的利用，并在编译时自动使用适当的“断言”生成的代码

这样，如果API中有一个“@CheckForNull”，那么函数的编写者甚至可以不记录它而侥幸逃脱！如果语义发生了变化，它的API将反映这种变化（比如“不再有@CheckForNull了”）

这种方法表明，对于“边界条件”，文档是额外的奖励，而不是强制性的做法

---

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

问题1

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

几乎从来没有

问题2

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

/**
 * 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);

//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);