api documentation and “value limits”: do they match?

Question :

api documentation and “value limits”: do they match?,

Answer :

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

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. 
* WarningThe 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. 
* WarningThe 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:

Read More  Open Source Actionscript 3 or Javascript date utility classes?

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…

Read More  Windows-based Text Editors

Edit:

This can influence the usage or not for

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.

Read More  Entity Framework vs LINQ to SQL

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.

That’s the answer api documentation and “value limits”: do they match?, Hope this helps those looking for an answer. Then we suggest to do a search for the next question and find the answer only on our site.

Disclaimer :

The answers provided above are only to be used to guide the learning process. The questions above are open-ended questions, meaning that many answers are not fixed as above. I hope this article can be useful, Thank you