Re: maxEntries in contents()

I consider clarification text to be on the order of a bug fix (if a
minor one) that should not require spec-like approval. If the use of
JavaDoc as a spec repository is a procedural inhibitor to improving
Jini in a way that doesn't itself change the spec then I would suggest
the spec shouldn't reside in the JavaDocs. But then again I feel that
way regardless. There's a lot of spec-motivated boilerplate text in
the JavaDocs that makes it more difficult than it need be to use the
Jini libraries. If the spec is to be holy, then how about we make the
JavaDoc less so--that way the masses can get their lay interpretation
of the spec in the modern tongue.
 
Jeff

 
________________________________

From: John McClain - Sun Microsystems, Inc.
[mailto:[email protected]]
Sent: Wed 11/30/2005 11:16 AM
To: [email protected]
Subject: Re: maxEntries in contents()



I have to admit, when I read "the maximum number of entries to remove
from the set via MatchSet.next calls" in Dan's message (for some
reason
I got Dan's message first....) I was a bit confused too....

Not sure why I didn't write something like "the maximum number of
entries to be yielded by MatchSet.next calls", or maybe "the maximum
number of entries to return before the MatchSet is considered
exhausted". I suspect I had latched onto the idea of next deleting
entries from the match set and wanted to stick with that notion.

As for modifying the JavaDoc I need to think about that. There is the
procedural issue that it is now an approved community standard and
certain types of changes would require a vote. More deeply we (Sun's
Jini team) try to keep non-normative text (like motivations, uses
cases,
examples, etc.) out of our specs.

One idea that does appeal to me is writing some sort of companion
document to the JavaSpace05/MatchSet/AvailabilityEvent JavaDoc that
can
include non-normative text, be less precise, and more user oriented. I
suspect it would focus on the expected usage models. Not sure what
would
be the best way to make this new document visible (then there is the
time problem too)



===========================================================================
To unsubscribe, send email to [email protected] and include in the body
of the message "signoff JAVASPACES-USERS".  For general help, send email to
[email protected] and include in the body of the message "help".

To view past JAVASPACES-USERS postings, please see:
http://archives.java.sun.com/archives/javaspaces-users.html