Document caching in AnnotatedTypeFactory.getAnnotatedType(Tree)

This seems to have been covered in some way in previous issues (#130, #498, #601), but I can't quite grok the overall current state of caching in AnnotatedTypeFactory. I saw in a profile of a checker we are building that a significant amount of running time is spent in AnnotatedTypeFactory.getAnnotatedType(Tree):

Further, while debugging I noticed some quadratic behavior for deeply-nested method call expressions, which we deal with often. E.g., if we have this code:

x.setProp1(...).setProp2(...).setProp3(...).setProp4(...)

Invoking getAnnotatedType for each call expression results in calling getAnnotatedType for each of the nested sub-expressions, and the results aren't cached.

It seems from previous discussions that more aggressive caching is quite subtle in terms of correctness. It might be worth having documentation somewhere on the current state of caching and why more aggressive caching is tricky to get right. Also I am wondering if a checker could opt in to more aggressive caching if the trickiness is checker-dependent. Finally, do some checkers add their own more aggressive caching, overriding the framework's default behavior?