Rather be well documented and embarassed as not-documneted and still very embarassed :)
Isn't there a way to have a deprecated free javadocs (so java docs for migrators and javadocs for newbies)? And the reason for suggesting a removal by date is to make sure that there is a quick removal of these members so that with every release the number of members deprecated to number of members dropped should come to be nice constant. (Now that would be an interesting research project).
