The documentation is correct and unambiguous.  Regular expressions just aren't very intuitive.

The documentation says "Causes the resulting RE to match 0 or more repetitions of the preceding RE, as many repetitions as are possible."  "as many repetitions of the preceding RE" means that:

  (a|ab)*

is equivalent to

  (a|ab)(a|ab)(a|ab)...

where "..." represents "add copies of the RE until it doesn't match".

Then you have to look at the documentation of '|' to see what it matches, and that documentation (already quoted) explains why the expanded pattern only matches 'a' in 'aba'.

Perhaps it would be clearer if it read "Causes the RE to be evaluated as if there were zero or more repetitions of the preceding RE, as many repetitions as produce matches"?