In GlassFish V3, here is what I'm doing (one example). I've created the annotation @Taxonomy, which takes a value of type Stability. This is what it looks like in the Javadoc. One can click through the annotation and see the actual definition of the stability level.
This is available at the java package level or class level. Overview Package Class Use Tree Deprecated Index Help PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES @Taxonomy(stability=UNCOMMITTED) Package org.glassfish.admin.amx.core Class level: org.glassfish.admin.amx.core Class AMXConstants java.lang.Object org.glassfish.admin.amx.core.AMXConstants @Taxonomy(stability=UNCOMMITTED) public final class AMXConstants extends java.lang.Object Keys for AMX metadata found in the various javax.management.Desriptors found in MBeanInfo and its contents. 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
