[jira] Created: (RIVER-383) Clearer Javadocs

["James Grahn (JIRA)" <ji...@apache.org>]

Clearer Javadocs
----------------

                 Key: RIVER-383
                 URL: https://issues.apache.org/jira/browse/RIVER-383
             Project: River
          Issue Type: Improvement
          Components: doc
            Reporter: James Grahn


The current Javaspace docs are part protocol specification, part implementation with some vital bits of information squirreled away in obscure reaches.

For instance, in the 9 paragraphs describing the behavior of "JavaSpace05.take (with collection)":
"If there is at least one matching Entry  available in the space, an invocation of this method must take at least one Entry. If more than one matching Entry is available, the invocation may take additional entries. It must not take more than maxEntries, but an implementation may chose to take fewer entries from the space than the maximum available or the maximum allowed by maxEntries."

The above is a broad protocol specification giving a lot of latitude to implementers (Collections.emptyList() matches the above description).   

The above documentation is frustrating to users because the definition is so amorphous.

It also takes some doing to track down the fact that the implementation does, in fact, limit the number of entries returned from a "take (with collection)".   That tidbit is stored within the outrigger *package* documentation, which reveals the setting and default (only 100).

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.