It is a joy to work with a clean, clearly defined API. As an API evolves some methods (or classes) will be deprecated over time. Often the method or class will not beremoved for compatibilty reasons.This does not mean that it should continue to be used. Of course, the deprecation should be documented and i Java the @deprecated javadoc tag is the perfect way to do this. It should explain why the method/class was deprecated and the preferred replacement.
Of course not all classes in a libaray form part of its API. Various conventions are followed such as *.impl.* or *.internal.* packages. Sometimes this hint is ignored by devlopers using the API and this inevitably leads to broken code when a new version of the library is released. One project which makes good use of the *.internal.* convention is the eclipse platform but some plugin developers insit on ignoring it!
One possibility is to use AspectJ to highlight design violations. Adrian Colyer has an example of something like this, using an Architecture aspect in Simplifying Enterprise Applications with Spring 2.0 and AspectJ .