Databases
StackOverflow2013
Postsdbo
POapi documentation and "value limits": do they match?
 

Note that there are some explanatory texts on larger screens.

plurals
  1. POapi documentation and "value limits": do they match?
    primarykey
    data
    text
    <p>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 ?</p> <p><strong>Note:</strong> I am not talking about <a href="https://stackoverflow.com/questions/20922/do-you-comment-your-code">comments within the code</a></p> <p>By "value limits", I mean:</p> <ul> <li>does a parameter can support a null value (or an empty String, or...) ?</li> <li>does a 'return value' can be null or is guaranteed to never be null (or can be "empty", or...) ?</li> </ul> <p><strong>Sample:</strong></p> <p>What I often see (without having access to source code) is:</p> <pre><code>/** * Get all readers name for this current Report. &lt;br /&gt; * &lt;b&gt;Warning&lt;/b&gt;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); </code></pre> <p>What I <em>like to see</em> would be:</p> <pre><code>/** * Get all readers name for this current Report. &lt;br /&gt; * &lt;b&gt;Warning&lt;/b&gt;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); </code></pre> <p><strong>My point is:</strong></p> <p>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 <em>how to use it</em>.</p> <p>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...</p> <p><strong>Edit:</strong> </p> <p>This can influence the usage or not for <em><a href="https://stackoverflow.com/questions/27578#73355">checked or unchecked exceptions</a></em>.</p> <p>What do you think ? value limits and API, do they belong together or not ?</p>
    singulars
    1. PO
      singulars
      1. PTAnswer
    1. This table or related slice is empty.
    1. PTQuestion
    1. USCommunity
    1. USVonC
    plurals
    1. PL
      singulars
      1. LTLinked
    2. PL
      singulars
      1. LTLinked
    1. PL
      singulars
      1. LTLinked
    2. PL
      singulars
      1. LTLinked
    3. PL
      singulars
      1. LTLinked
    1. This table or related slice is empty.
    1. PO
      singulars
      1. PTAnswer
    2. PO
      singulars
      1. PTAnswer
    3. PO
      singulars
      1. PTAnswer
    1. VO
      singulars
      1. POapi documentation and "value limits": do they match?
      1. This table or related slice is empty.
      1. VTUpMod
    2. VO
      singulars
      1. POapi documentation and "value limits": do they match?
      1. This table or related slice is empty.
      1. VTUpMod
    1. This table or related slice is empty.
 

Querying!

 
Guidance
A row detail

Detail views are divided into sections. All the information in the data section comes from columns in the selected row. The other sections display data from other, related rows.

Related data can be related in a to-one or a to-many fashion. Captions of data related in a to-many fashion link to a list view showing a filtered view of the table.

Try moving around until you find a non-empty to-many entry and click on the label to get to one. You can move back to the root by clicking on the database name in the header.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload