This package "contains" other packages that specify parts of the JDK, and other libraries for JML.
We use the following conventions for the specifications.
Don't copy any method bodies or other executable code (such as initializer blocks) into the specifications. Code is certainly something that we need to avoid due to copyright issues.
For the same reason, don't copy the javadocs into the specifications.
It's important that you don't add a specification for a type that is incomplete. That is, don't give the interface for just a single method, but include all of the (public and protected) interface of each type you specify.
To deal with differences among JDK versions, you may have to include declarations for additional methods that are not in earlier versions of the JDK in your specification files.
The set of interfaces you specify should be closed in the sense that the tests pass without having to have other information available. In some cases this will mean you will have to specify extra types to allow the tests to pass.
At present the only types that we can compile with jmlc are interfaces. To do that automatically, use a .spec file for each interface instead of some other suffix. For other files, any suffix except .java is fine, but we suggest using .refines-spec or .refines-java.
Creating initial versions of these specifications can be done with the jmlspec tool. Use the --protected flag so that you get (only) the public and protected members and ignore the private and package visibility members.
We suggest that you only specify normal behavior, at least at first.
You should only document public and protected features of these classes, and ignore package and private visibility features.
When in doubt about whether to use a ghost field or a model field, use a model field.
If an import is only used in the bodies of methods and other executable code, but is not needed in the code's interface, then you should remove it from the specification. In particular, this will allow us to keep references from the com.sun packages out of the specifications.