Agree with stack that the comment can be simplified. Also as stated in
HBASE-2038, this reseek only works correctly on row boundaries, so the API should capture this and only accept a rowkey (rather than a KV).
Then maybe the comment could say something like this:
"Seek forward to the first KV matching the passed rowkey.
Only forward seeking is allowed, otherwise the behavior is undefined."
There might be problems with this approach too. What if the scanner already saw some KVs for this rowkey? It puts a lot of burden on the caller that we only seek forward.
As an aside:
Looking back at the various conversations, I actually have not heard a convincing argument on why using a Filter that returns the standard SEEK_NEXT_USING_HINT does not work. It would be doing a little bit more work (because each store would separately need to seek, and it needs to look at at least one more KV to decide to skip ahead), but that would still be huge win over a full scan that needs to look at every KV.
Filters do not have the above problems, since they are inherently per column family.
You wouldn't use filterRow() but use filterKeyValue() together with getNextKeyHint()