Margot Miller wrote: > Hey All, > > I am derailing this case as it misses the non-controversial requirement > for a fast track and would like an email vote on this case by > Friday May 15th. > > My impression from today's meeting was that LSARC will have > a future case that will address the issue of how to publicize interface > classifications for jar files and that it was okay for this project > team and > other teams to optionally ship a man page for a jar file. This would > be setting > precedent. > > Below is the proposed verbiage for the opinion. > > The project team is delivering a man page for the java jar file. 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 > shipped these man pages. This case proposes letting the project team > and > others optionally ship a man page for a jar file. > > I vote against.
I'm presuming you're voting against this case as spec'd, with the offered opinion, correct? The project team hasn't been given a chance to make any advised or required modifications, so it seems a bit imprudent to deny a case in that manner. The intent here is that the man page inclusion precedent will be set here and now, right? If the vote sustains for approval with a man page, then there's no need to bring another case forth, right? Seems like Jim's gap would be addressed in that case. Or should the "optionally" token in the opinion text be taken as a failure to cover the gap? On the topic, though, I think Jim brings a very good point -- how does the project team communicate the expected stability? Lloyd brings an interesting solution with the use of Java Attributes as documentation decoration, although I have a few issues with it on technical grounds. For those not on the call, I see the problem as this: At some point, Sun must have established the precedent and the _expectation_ that stability levels of most types of interfaces were to be expressed to consumers of those interfaces in the man pages. I'm sorry I can't quote chapter and verse. This is, as far as I'm aware, a communication norm that I don't see in other systems, Sun originated or otherwise. Java certainly does not have it as part of any standard, nor does Linux, as we discussed in the bsh vs. beanshell debate in PSARC. As we're ramping up integration of java components, we're creating new gaps from old practice. One of these is the nomenclature surrounding the naming of the jar files themselves (jars as "libraries"), which I won't go into here. The other is the point which Jim raised -- there's currently no expected way to communicate stability level other than man pages. Adding man pages to java jar projects (projects which deliver only .jars) _feels_ wrong, since the consumers of these jars aren't going to expect to find a man page -- they're on a very different usage model than most other consumers of C libraries and command line interfaces. Consumers in this case typically use JavaDocs as their source of API information, and that _feels_ like a better place to put that information. If the man pages are explicitly NOT to be delivered with "jar" projects, then where is the stability level expressed? If in JavaDocs, then what does that look like, assuming we need precision for that nomenclature? Does the very same taxonomy even apply to jars? The current taxonomy is, as a core component of its definition, dependent on release versions of Solaris. Obviously, java jar's are more tightly coupled to Java versions than on OS release versions, no? > > Thanks, > Margot > > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc at opensolaris.org
