> I'm more concerned on the actual size returned by getValueCount(): as you say the javadoc is very limited, but to me it looks like it's not the max number of values in any document but rather the count of all unique terms across all documents , so this could be billions even if each document had just a couple of different terms.

why do you interpret it this way? IMO that would not even make sense. How would the "count of all unique terms across all documents" makes sense for a single SortedSetDocValues instance. AFAIC it is the way I described, but I will have a closer look for sure.