This RFE is summarized in 
http://openide.netbeans.org/servlets/ReadMsg?msgId=387201&listName=dev

JSR-175, A Metadata Facilty for the Java Programming Language, should also
be considered in the context of this RFE.

Repeated from the above post:

    I first saw the @unstable suggestion on nbdev,
    http://www.netbeans.org/servlets/ReadMsg?msgId=383587&listName=nbdev,
    from Alvin Thompson, bug # 4748349.  (Hmm, looks like
    the bug # must be wrong.)  Ok, quoting from Alvin's post:

       A DESCRIPTION OF THE PROBLEM :
       It would be nice to have an 'unstable' javadoc keyword,
       which would work similarly to the 'deprecated' keyword, to
       warn developers that the API of the documented item is still
       under development and subject to change. This should be
       trivial to implement since 'deprecated' already produces the
       desired functionality; all you would have change is the
       warning/error message the compiler spits out.

    I think this is clearly the right way to go, that is,
    developers mark the APIs as unstable/experimental/evolving,
    and tools warn users about it.

    Let me take the suggestion further and suggest that we
    take more of a leadership role here.  We could change the
    internal compiler to implement such functionality and support
    a new JavaDoc keyword.  We can also do as Tor has suggested
    here and provide a doclet to differeniate these APIs in 
    the JavaDoc, and we would probably want to change the code
    completion as well.  As Alvin pointed out. the code in the
    compiler should be easy as its just a subset of the current
    @deprecation support.

    Our tools would be adding value, there would be no incompatibility
    issues with people using different compilers, just a loss of
    advanced functionality, and it would serve a good existence
    proof for the JDK compiler team.