Docs falsely state TaggedFieldSerializer doesn't read deprecated fields

[cypherdare]

The docs say "fields marked with the @Deprecated annotation will be ignored when reading old bytes", but this is not the case. The read() method reads all tagged fields that it encounters, regardless of whether they are deprecated.

It makes sense that it does this. Deprecated fields still have to be read if encountered, so the stream will be at the correct location for subsequent fields and objects in the stream.

Some alternative ways to fix this:

1. Fix the docs to say that deprecated fields are not written, but they are still read if encountered.

2. Change functionality so objects within the deprecated field are read but not assigned to the field. Users must take care that those objects cannot safely be lost to the GC. For example, if they require native memory cleanup. Anyone in this situation has already been leaking memory if they were relying on the feature as described in the docs.

Going off of option 2:
#521 adds the annexed option to Tags so they are encoded chunked. Maybe rename annexed to skippable, and it serves a dual purpose. Skippable fields have the extra bonus feature of not being read if they get deprecated. I'm not sure if this adds enough value to be worth the more complicated API, though. You would need to anticipate which fields might become deprecated later, and eat the cost of chunked encoding for the possible benefit of slightly faster read times (but only when old data is read in newer applications).

I personally think option 1 makes more sense. It allows manual cleanup of deprecated fields in case that's necessary, and the user could easily null-out the deprecated fields. Or we could add an option to TaggedFieldSerializerConfig to turn on option 2.

[magro]

Option 1 sounds good btw! :-)

[NathanSweet]

I've fixed this in a local branch, this issue will be closed when it is merged.