See small comment interspersed. Cheers,
Greg. On Tue, 2007-01-09 at 04:32, Dan Creswell wrote: > > (Mark Brouwer) > > 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. > > Ugh, it's a little too subjective for me. > I'd be happier with separate specifications, however that suggestion has gone over like an iron balloon (translation for non-English speakers: it was suggested and debated at length, and wasn't taken up by the community). So in cases where the API and the specification are inseparable (like Mark suggests below), I agree with Mark that we may as well have the spec inside the package documentation. That way it is subject to version control and the normal suggest/discuss/vote/commit process. One qualifier on the suggestion; I'd only want specs rolled in with generic API's. For instance the JavaSpaces spec would be fine in the net.jini.space package, but not with the Outrigger implementation. > > I see no problem in moving most of the Lease Specification > > http://java.sun.com/products/jini/2.1/doc/specs/html/lease-spec.html to > > the package documentation of net.jini.core.lease as long as people get > > linked there from an overview about leasing to that package. > > > > > Dan.
