The main thing for me isn't that the function and its documentation-pseudocode are in sync (though in the long run this is desirable).  What's important to me is that the function have a sensible, relevant signature in Python.  There was simply no way to express the "times argument behaves differently when passed in by position vs. by argument" semantics in a signature.

I agree the new implementation is an improvement.  But there's still no way to represent repeat's signature in Python.  This is because "times" is an optional argument without a valid default value.  It should always hold true that calling a function and explicitly passing in an optional argument's default value should behave identically to not specifying that argument.  But there's no value I can pass in to "times" that results in the same behavior as not passing in "times".  That's why I prefer the "times=None" approach.

At some point I expect to get "nullable ints" into Argument Clinic (see #20341 ).  Once that's in, I propose we convert itertools.repeat to work with Argument Clinic, as follows:
  * We use a nullable int for the "times" parameter.
  * The "times" parameter would have a default of None.
  * If times=None, repeat would repeat forever.
repeat would then have an accurate signature.

Raymond: does that sound reasonable?