Consider this API specification:

http://java.sun.com/javase/6/docs/api/javax/tools/DiagnosticMessage.Kind.html#values()

Contractions should not be used in API specifications. In particular,
the static values method of enum types uses "they're" (twice):

    Returns an array containing the constants of this enum type,
    in the order they're declared. This method may be used to
    iterate over the constants as follows:

    for(DiagnosticMessage.Kind c : DiagnosticMessage.Kind.values())
            System.out.println(c);

    Returns:
        an array containing the constants of this enum type, in the
        order they're declared

It should be: "in the order *they* *are* declared".
As each enum type has static methods that are generated by the compiler
the standard doclet generates API documentation for these methods.

The standard doclet should not use contractions in such cases.