Update annotation for pygame.Surface.blits() (and some other tidy ups)

[rethanon]

Updated annotation for pygame.Surface.blits() to correct the keyword used and expected parameters.

[rethanon]

This is to fix issue #2693

[Starbuck5]

Alright, this might not be as simple as I thought.

blit looks wrong as well. The area argument should take a _CanBeRect, and the destination argument looks like it should be a union of _Coordinate and _CanBeRect.

And those changes should be ported to blits as well, right, because blits takes a sequence of blit arguments.

Also, when I was checking the docs for this I noticed that the parentheses are unbalanced in the definitions!
Cmon blits:

If you want to fix that as well, it would be in docs/reST/ref/surface.rst. And you can regenerate the docs locally with setup.py docs to test your changes.

[rethanon]

OK thanks, working on this, just having a problem with setup.py docs as it says I need Microsoft Visual C++ 14.2 or greater, so I'm having to install it.

[rethanon]

I've made the updates but I can't seem to regenerate the docs, I get errors on both my Windows machine and my Mac when I run setup.py docs. In any case I was only removing a couple of ) nothing major.

[Starbuck5]

Uh, that's weird.

setup.py docs should just build the docs, not pygame.

I think the types look good now.

For the docs I was thinking you would have to add an ( in the left to represent the sequence that the blit arguments are in. Would that be right?

[rethanon]

I think the types look good now.

For the docs I was thinking you would have to add an ( in the left to represent the sequence that the blit arguments are in. Would that be right?

Oh man, yeah you're right, sorry. I only recently started using Black to format my code correctly and I misread the number of ( I had in the code I was testing, sorry amended now.

The issues with running setup.py docs are different on Mac vs my Windows PC so I'll look into them in greater detail later (although I the issue on Mac mentions an SDL2 error so I don't want to look at fixing that until I've finished helping with #2671)

[rethanon]

Uh, that's weird.

setup.py docs should just build the docs, not pygame.

I've taken a closer look at the error I'm getting on my Windows machine and the first line starts with
WARNING, No "Setup" File Exists, Running "buildconfig/config.py"

I assume it's then trying to build pygame rather than just the docs.

[rethanon]

Added a few minor updates to annotations in mixer.pyi, also corrected a couple of minor typos in the mixer docs.

[Starbuck5]

This one still needs another parenthesis.

[rethanon]

Somehow I didn't even notice that one! Thanks.

[Starbuck5]

This probably returns whether init was successful, not just True.

Also, if you're going to fix that you've got to fix the docs too, because they say it returns None.

[rethanon]

My fault, getting mixed up with which changes I'd made as I was looking at my fork on 2 different machines, think I committed the wrong one as the other one I'd changed to bool, not True. Also updated docs, apologies. I feel like a noob!

[Starbuck5]

Alright, I opened a broader issue about the mixer.init() thing, #2702, so I think it would be best to take the mixer.init() docs and types changes out of this PR.

Thanks for pointing that out though. I think it should be fixed across several modules, by changing the code to match the docs, rather than the other way around.

And the parentheses should be after blit_sequence=, since the sequence is the value of the keyword argument.

Also I guess I need to fix setup.py docs so that people who don't have the full setup to build pygame can build the docs.

[rethanon]

Reverted changes for mixer docs and types and fixed parentheses in surface.blits docs. Thanks.

[ankith26]

Looks good to go! Thanks for the PR! 🎈

[Starbuck5]

This looks good to me as well. 👍

Thanks for contributing!