See inline. margot wrote: > Hey All, > > Here is the draft opinion. > > Please review/comment. > Thanks > Margot > > ****************** > > > sun > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion at sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. Does that convey enough > of the stability of the jar and its methods to the developer? Open ended questions don't belong in the opinion, so please either take this out or state a position. > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, html, > and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn?t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). Do you really want to state that LSARC has a question about this?
Without a concrete proposal on what each project should use or even whether they need to state the interface classification other than in the ARC case, I predict that they won't. -- mark
