Worth noting: 'man' pages are wholly inadequate to document some jar files; one would be in the awkward position of enumerating all the classes, and possibly all the methods/constants in those classes.
There are jar files that are nothing but interfaces, some that are interfaces and code, some that are mostly code. I don't think a man page will ever be in a position to do anything but a very coarse (and therefore risk) job at documenting what's the stability. Lloyd On May 12, 2009, at 3:28 PM, Mark Martin wrote: > 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 > Lloyd Chambers lloyd.chambers at sun.com GlassFish Team
