"how do we communicate the interface classification of a jar file"
This is a multi-level. Plenty of jar files contain classes or classes with methods and other stuff which is not intended for public consumption. Simply because somthing is "public" or "protected" is not a good way to assume it is an API. So classifying a jar file is ultra-coarse, and maybe not a good idea unless qualified with: - all classes and methods unless otherwise annotated (risky) - no classes unless explicitly annotated (better) eg an "opt out" or "opt in" approach. Lloyd On May 12, 2009, at 3:57 PM, Margot Miller wrote: > The case hasn't been denied; it's been derailed so an opinion can be > written and it will be clear if precedence has been set or not with > this case. > > From the LSARC meeting today, it seemed like the majority of > the committee thought it was fine for the project team and other > teams to ship a man page. I don't think that is the right way > to go, in that some jar files will have man pages, some won't > and Java developers probably won't look for a man page > anyway. > > I think Jim identified correctly a real problem - how do > we communicate the interface classification of a jar file to the > end user. I think we need a comprehensive and > consistent solution. And the javadocs proposal has a lot of > merit to it. > We are voting on whether the project team should be allowed > to ship the man page. (I thought the majority wanted that > but need to take an explicit vote) > > So if after the vote, I am in the minority, than the case is approved > and I write a section stating the minority opinion. If after the > vote, > I am in the majority, then the case is approved, the team doesn't > ship a man page, and the minority can write their section of > the opinion if they chose. > > Margot > > > Mark Martin wrote: >> >> 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
