I think your interpretation of the documentation is reasonable. In fact, your understanding matched mine until I started experimenting.

Assuming that the SubsetCases[] works as designed, "overlap" is based on the elements of the first argument.

To illustrate, adding an additional a gives you the results we both expected:

SubsetCases[{1, 2, 3, a, a, a, b, c}, {a, _Integer}]

returns:

{{a, 1}, {a, 2}, {a, 3}}

So, "overlap" seems to be controlling whether elements of the first list can be reused.

Unfortunately, allowing overlaps probably does not give what you want. For example:

SubsetCases[{1, 2, 3, a, a, b, c}, {a, _Integer}, Overlaps -> True]

returns

{{a, 1}, {a, 2}, {a, 3}, {a, 1}, {a, 2}, {a, 3}}

Fortunately, I think there is a fix that might work for you:

Union[SubsetCases[{1, 2, 3, a, a, b, c}, {a, _Integer}, 
  Overlaps -> True]]

returns what we both originally expected to see:

{{a, 1}, {a, 2}, {a, 3}}

Knowing how it actually works, I think that the function might be working as designed. But, I think they could have done a better job explaining it in the documentation. And of course, some additional examples that highlights how overlap works would help.

Good luck.

Francisco:

You are welcome. Happy to help.

Toni:

Thanks for the clarification.

Is there any way to get this explanation and a few examples that illustrate how overlaps works into the documentation?

Thanks for the question, we'll improve the documentation.