Re: maxEntries in contents()

There's been recent conversation about documentation for Jini (books,
on-line, etc.). I'm of the opinion that Jini's continued success
depends on a good new user experience--we need fresh blood! JavaDoc
that is intended for a library user to read (rather than a spec
implementor) is one way to improve that experience. However, writing
lots of JavaDoc isn't easy and it wouldn't do to rip out the current
spec docs as I don't imagine any one of us has the time to write new
JavaDocs to replace them.
 
I would then propose to use the current spec documentation as the
starting point for JavaDocs. Over time these docs will begin to
diverge from the spec docs (maintained elsewhere), primarily through
annotations such as the one that prompted this thread and the deletion
of extraneous content that an API user wouldn't require.
 
There's a side benefit to this proposal that I think deserves special
mention. I know from the 9th Community Meeting that there's interest
on the Jini team in finding ways to have the community participate
more actively in the development of Jini. I think this is one way to
lower a barrier to entry--making it easier for documentation changes
to be added to the code-base. A further step would be to have Jini in
CVS/Subversion so that a doc change submitter can see their work added
to the code within a few days (or so) of submission.
 
Jeff

________________________________

From: John McClain [mailto:[email protected]]
Sent: Fri 12/9/2005 7:45 AM
To: [email protected]
Subject: Re: maxEntries in contents()



Something I should have made clear in my original email. The notion
that
"JavaDoc == spec" is a decision Sun's Jini team has made for our new
specs (most of our pre 2.0 specs are not the JavaDoc). It is not
required by the JDP, what form a spec takes is ultimately up to the
owner (of course if the community finds the form unacceptable they can
reject it for that reason).

John McClain - Sun Microsystems, Inc. wrote:

[...]

> As to the "JavaDoc == spec" question, I don't think I have anything
to
> add. I have done it both ways and there are advantages and
disadvantage
> to both (for writer and reader), someone just needs to tell me if we
are
> switching.
>
> Jeff Ramsdale wrote:
>
>> 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.
>

======================================================================
=====
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



===========================================================================
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