api文档和“价值限制”：他们匹配吗？ [英] api documentation and "value limits": do they match?

问题描述

你经常在API文档中看到价值限制的描述以及经典文档吗？

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

由value limits表示：

• 可以支持一个空值（或一个空字符串，或...）？


• 一个返回值可以为null或者保证永远不为null ，或...）？
  
  $ b
  $ b

  我经常看到（无需访问源代码）是：

    / ** 
   *获取当前报告的所有读者姓名。 < br /> 
   *< b>警告< / b>报告必须先发布。 
   * @param aReaderNameRegexp过滤器，以便只返回与regexp匹配的读者
   * @return读者名称数组
   * / 
   String [] getReaderNames（final String aReaderNameRegexp）; 
    

  我喜欢看到的会是：

    / ** 
   *获取当前报告的所有读者姓名。 < br /> 
   *< b>警告< / b>报告必须先发布。 
   * @param aReaderNameRegexp过滤器，以便仅返回与regexp匹配的读者
   *（可以为空或为空）
   * @return读者名称数组
   *尚未发布，
   *空数组，如果没有读者匹配条件，
   *读者名称数组匹配regexp，或所有读者，如果regexp为null或空）
   * / 
   String [] getReaderNames（final String aReaderNameRegexp）; 
    

  我的观点是：

  
  
  

  当我使用带有getReaderNames（）函数的库时，我经常甚至不需要读取API文档来猜测它的作用。但我需要确保如何使用它

  。
  
  
  

  我唯一需要关注的是，当我想使用这个函数是：参数和返回值的期限？这是我需要知道的安全设置我的参数，并安全地测试返回值，但我几乎从来没有看到这样的API文档中的信息...

  
  
  

  修改：

  
  
  

  这可能会影响 已选中或未选中的例外

  。
  
  
  

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

  解决方案

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

  
  
  

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

  
  
  

  但是，像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屋！