Major Description
The current back compat introduced in LUCENE-4524, does not really help the users calling e.g. LeafReader.termDocsEnum() or LeafReader.termPositionsEnum(), because the former's return value changes to PostingsEnum, its superclass, and the latter got removed.
It also does not help users using TermsEnum.docs() or TermsEnum.docsAndPositions() which got removed and just replaced with postings().
DocsEnum is different, but not deprecated, instead only used by some codecs as a convenience class. DocsAndPositionsEnum is removed.
I think we can do this a little better. First, we need to fix trunk to work the way we want it to look. I think we should have LeafReader.postings() and TermsEnum.postings(), and everything should use PostingsEnum. This is simplest.
But in 5.x, I think we should have DocsEnum and DocsAndPositionsEnum which are deprecated, to help guide the user.
The "sugar" methods on LeafReader that exist in 5.0 (termDocsEnum(), termPositionsEnum()) should be deprecated (with message to use postings()) and final, and can just wrap PostingsEnum. There is no reuse and flags here so this is very simple.
On TermsEnum its more complicated, but i dont think impossible. We should add back deprecated and final termDocsEnum() and termPositionsEnum() (with message to use postings()) and these deprecated ones can have an instanceof check, unwrapping back to PostingsEnum before they invoke postings behind the scenes.
For the 2 remaining ones on TermsEnum that take flags, thats the most tricky. I actually think we shouldn't change the existing constant values when we dont have to. And I don't think the names FLAG_FREQS are special, i'd rather these just be constants like FREQS. I looked thru JDK constants (http://docs.oracle.com/javase/7/docs/api/constant-values.html) and only one class uses this FLAG_xxx prefix.
So I think we should have PostingsEnum.FREQS etc with new values, not conflicting with the old FLAG_FREQS etc values (which we can add back, deprecated, to DocsEnum and DocsAndPositionsEnum). We can even add a check to the deprecated methods that only valid values are passed.
This just means we have contained back compat, only for deprecated and final sugar methods in LeafReader and TermsEnum, and the 2 deprecated classes. I think we can live with that and it would save users pain.