Home/ Questions/Q 34125
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-10T14:01:45+00:00

Do you often see in API documentation (as in ‘javadoc of public functions’ for

  • 0

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 ?

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. 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.

    • 0