Variant toString represesentations cause problems in client code

[GoogleCodeExporter]

The API documentation for toString is rather weak.  Although toString is 
part of the public API for every object, not every object implements 
toString for public consumption.

We need an annotation that will denote when toString returns values are 
subject to change without warning.  This allows developers to be confident 
that API users are not parsing output of toString for values, when the 
toString implementation was designed for debugging purposes.  For 
instance, Component subclasses produce a list of parameters and values are 
part of their toString.  There is no specification on the order or content 
of these values.  They can change from revision to revision.  Any client 
code relying on such a toString implementation should be considered 
fragile (at best).

I recommend that a @Volatile annotation for such a case.  Though @Volatile 
might be confused with the keyword and/or connote some expectation of 
concurrecy, so another annotation name is probably better (but it's a 
place to start).

Original issue reported on code.google.com by karlgsch...@gmail.com on 14 Aug 2009 at 7:35