Mailing-List: contact river-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: river-dev@incubator.apache.org
Received-SPF: neutral (herse.apache.org: local policy)
Message-ID: <45A36B2B.4000908@cheiron.org>
Date: Tue, 09 Jan 2007 11:15:07 +0100
From: Mark Brouwer <mark.brouwer@cheiron.org>
User-Agent: Thunderbird 1.5.0.9 (Windows/20061207)
MIME-Version: 1.0
To: river-dev@incubator.apache.org
Subject: Jini documentation [Was: Re: How to start from here?]
References: <459A7EB9.8020301@cheiron.org>
 <45A24BBE.5010300@cheiron.org>	 <45A2598F.20308@Sun.COM>
 <45A25B72.4080907@cheiron.org>	 <45A25C64.2030404@Sun.COM>
	 <e202160f0701081150o2b1ebd7cp4414d369c517537c@mail.gmail.com>
	 <45A2C075.9080006@cheiron.org>
 <e202160f0701081602w64c1ec4eqc46f2d265d5e60a8@mail.gmail.com>
 <45A2DE91.4080208@wonderly.org> <45A355A9.8050108@cheiron.org>
 <45A36124.2010303@dcrdev.demon.co.uk>
In-Reply-To: <45A36124.2010303@dcrdev.demon.co.uk>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

I move to a different subject because I think it is better if we have
each roadmap item in a separate thread.

Dan Creswell wrote:
> Couple of comments inline but I'd like to suggest something of a
> strategic option.  For me, at this stage, moving the specs around or
> whatever is a detail (an important one) but I think we need a plan for
> what we're trying to achieve overall - something like:
> 
> (1) Figure out what documentation we think we need overall
> 
> (2) Figure out what we have
> 
> (3) Figure out how (2) intersects with (1)
> 
> (4) Fill in the gaps
> 
> (5) Move it around 'til we like where it all lives
> 
> Now it might be y'all have answers to the above already in which case,
> great - let's get 'em all out here.

It is important to talk about what kind of documentation we need and
something we should get rolling, but to me it is not a priority and as
such also not something I expect to spend much time on.

The only thing I find important at this stage is whether we are going to
follow a common rule about how we are going to spec and keep that
uniform. E.g. if there is maintenance on the lookup and discovery
specification are we going to move that over in a fashion comparable
with the newer specs or are we going to defrost the current HTML specs
to the minimum that we can alter a few paragraphs.

>> But specs that are required for a reimplementation or that tell you what
>> to expect in the not that less straightforward cases (which my mind
>> always tend to look for) should IMO be where they belong and that is
>> close as possible to the code that I have to my avail in my IDE.
>>
> 
> Hmmm, knowing you as I do, I'm not surprised - me, I prefer the specs
> separate and I cross ref into JavaDoc when I need to.

Can't resist, why should one be surprised ;-) I think it is completely
logical to try to find the semantics of a method at the method level.

Going to a spec to have to find out whether a lease duration can be
negative or even zero should be something the javadoc for the
'duration' argument at the method level should tell me, and the
IllegalArgumentException should make it even more obvious.

I've seen too many bugs lingering in code that were there because the
distance between code and semantics was too far apart. And often I was
not in the position to spank those people responsible for I had to admit
knowing the semantics was a job too much effort for the 21 century man.
-- 
Mark