api文档和“价值限制”：他们是否匹配？ [英] api documentation and "value limits": do they match?
问题描述
注意：我不是在说代码中的评论
按价值限制，我的意思是：
- 可以支持空值（或一个空字符串，或...）？
- 做一个'返回值'可以为null或者保证永远不会为空（或者可以是空 或...）？
示例：
我经常看到（无权访问源代码）是：
/ **
*获取此当前报告的所有读者名称。 < br />
*< b>警告< / b>报告必须首先发布。
* @param aReaderNameRegexp过滤器，以便只返回与regexp
* @return读取器名称匹配的读取器名称
* /
String [] getReaderNames（final String aReaderNameRegexp）;
我喜欢看到将是：
/ **
*获取此当前报表的所有读者名称。 < br />
*< b>警告< / b>报告必须首先发布。
* @param aReaderNameRegexp过滤器，以便只返回与regexp
*（可以为空或为空）的读者匹配
* @return读取器名称数组
*（如果报告为null尚未发布，
*空数组，如果没有阅读器匹配条件，
*读者名称数组匹配正则表达式，或所有读者如果正则表达式为null或空）
* /
String [] getReaderNames（final String aReaderNameRegexp）;
我的观点是：
当我使用一个带有getReaderNames（）函数的库时，我通常甚至不需要阅读API文档来猜测它的作用。但我需要确保如何使用它。
当我想使用这个功能时，我唯一关心的是：我应该期待什么参数和返回值的期限？这就是我需要知道的，以安全地设置我的参数并安全地测试返回值，但我几乎从来没有看到API文档中的那种信息...
编辑
这可能会影响到 已选或未检查的例外 。
你觉得怎么样？价值限制和API，它们是否属于一起？
我认为他们可以属于一起但不一定有属于一起。在您的情况下，似乎有限的限制被记录在一起，它们出现在生成的API文档和智能感知（如果语言/ IDE支持）。
$ b $我认为这也取决于语言。例如，Ada具有一个受限整数的本地数据类型，您可以在其中定义整数变量，并明确指出它只会（并且始终）在某个数值范围内。在这种情况下，数据类型本身表示限制。它仍然可以通过API文档和智能感知来发现，但不会是开发人员在注释中指定的内容。
然而，像Java这样的语言而C＃没有这种类型的限制整数，所以开发人员必须在注释中指定它是否应该成为公共文档的一部分。
Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation ?
Note: I am not talking about comments within the code
By "value limits", I mean:
- does a parameter can support a null value (or an empty String, or...) ?
- does a 'return value' can be null or is guaranteed to never be null (or can be "empty", or...) ?
Sample:
What I often see (without having access to source code) is:
/**
* 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);
What I like to see would be:
/**
* 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);
My point is:
When I use a library with a getReaderNames() function in it, I often do not even need to read the API documentation to guess what it does. But I need to be sure how to use it.
My only concern when I want to use this function is: what should I expect in term of parameters and return values ? That is all I need to know to safely setup my parameters and safely test the return value, yet I almost never see that kind of information in API documentation...
Edit:
This can influence the usage or not for checked or unchecked exceptions.
What do you think ? value limits and API, do they belong together or not ?
I think they can belong together but don't necessarily have to belong together. In your scenario, it seems like it makes sense that the limits are documented in such a way that they appear in the generated API documentation and intellisense (if the language/IDE support it).
I think it does depend on the language as well. For example, Ada has a native data type that is a "restricted integer", where you define an integer variable and explicitly indicate that it will only (and always) be within a certain numeric range. In that case, the datatype itself indicates the restriction. It should still be visible and discoverable through the API documentation and intellisense, but wouldn't be something that a developer has to specify in the comments.
However, languages like Java and C# don't have this type of restricted integer, so the developer would have to specify it in the comments if it were information that should become part of the public documentation.
这篇关于api文档和“价值限制”：他们是否匹配？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
