I agree the doc could be clearer and Ned's example is very good. However I'd go one step forward and add a further elaboration of how the method works. This is the current doc (in default branch):

  Return a copy of the string where all tab characters are replaced by zero or more spaces, depending on the current column and the given tab size. The column number is reset to zero after each newline occurring in the string. If tabsize is not given, a tab size of 8 characters is assumed. This doesn’t understand other non-printing characters or escape sequences.

I'd say this (note new second sentence):

  Return a copy of the string where all tab characters are replaced by zero or more spaces, depending on the current column and the given tab size. Every time a \t char appears in the string, the text before it gets padded with spaces until the next tab position is reached. The column number is reset to zero after each newline occurring in the string. If tabsize is not given, a tab size of 8 characters is assumed. This doesn’t understand other non-printing characters or escape sequences.

And then follow with Ned's example.