language agnostic - api documentation and "value limits": do they match? -

do see in api documentation (as in 'javadoc of public functions' example) description of "value limits" classic documentation ?

note: not talking comments within code

by "value limits", mean:

• does parameter can support null value (or empty string, or...) ?
• does 'return value' can null or guaranteed never null (or can "empty", or...) ?

sample:

what see (without having access source code) is:

/**  * readers name current report. <br />  * <b>warning</b>the report must have been published first.  * @param areadernameregexp filter in order return reader matching regexp  * @return array of reader names  */  string[] getreadernames(final string areadernameregexp); 

what like see be:

/**  * readers name current report. <br />  * <b>warning</b>the report must have been published first.  * @param areadernameregexp filter in order return reader matching regexp   * (can 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 readers if regexp null or empty)  */  string[] getreadernames(final string areadernameregexp); 

my point is:

when use library getreadernames() function in it, not need read api documentation guess does. need sure how use it.

my concern when want use function is: should expect in term of parameters , return values ? need know safely setup parameters , safely test return value, yet never see kind of information in api documentation...

edit:

this can influence usage or not checked or unchecked exceptions.

what think ? value limits , api, belong or not ?

i think can belong don't have belong together. in scenario, seems makes sense limits documented in such way appear in generated api documentation , intellisense (if language/ide support it).

i think depend on language well. example, ada has native data type "restricted integer", define integer variable , explicitly indicate (and always) within numeric range. in case, datatype indicates restriction. should still visible , discoverable through api documentation , intellisense, wouldn't developer has specify in comments.

however, languages java , c# don't have type of restricted integer, developer have specify in comments if information should become part of public documentation.