Improved blit() docs

[itzpr3d4t0r]

Follows #2259. This one aims to improve the Surface.blit() function's docs since it's one of pygame's most used functions. I heavily encourage feedback as this is just a starting point. I tried to make docs easy to read and comprehend to a beginner but i may have rephrased some things wrong and/or made big mistakes.

Added:

• More detailed explanations of the dest and area parameters.
• More notes about when the blit will be skipped/positioning with not normalized rects.
• Explaination of what the special_flags parameter does (something that was completely absent before) and a whole “Special Flags” section that explains the different blending flags and how they affect the blit operation.

Removed:

• Mentions of specific versions of pygame where certain special flags were added.

OLD:

NEW:

The blit docs no longer list all blend flags and the blend flag descriptions have been moved to a separate section in the Surface object description:


This is to offload function docs of a repetitive blend flags description while providing a more in depth description of what each flag does.

[Starbuck5]

Here's an idea to chew on. What if the special flags explanation was a completely separate page, like the list of default colors in pygame.color. Right now the function is more daunting to look at because the description is so detailed, and a lot of that length is now coming from the special_flags documentation.

[itzpr3d4t0r]

Here's an idea to chew on. What if the special flags explanation was a completely separate page, like the list of default colors in pygame.color. Right now the function is more daunting to look at because the description is so detailed, and a lot of that length is now coming from the special_flags documentation.

Yeah I have kind of the same feeling there, but for now i guess i could just move the flags to the surface class and mention that in the blit docs. While this may not be a long term solution, it should give me some more time to work on the Surface class, make that better, and move flags out of there. Though idk if it's strictly necessary to create a separate page as for now we only got a handful of flags so yeah, we shall see.

[Starbuck5]

Just for reference this is what I'm talking about: https://pyga.me/docs/ref/color_list.html. Whole separate page not in the modules top bar.

[itzpr3d4t0r]

Here's an idea to chew on. What if the special flags explanation was a completely separate page, like the list of default colors in pygame.color.

Should this be implemented in this PR or a followup?

[Starbuck5]

I just don't like that this PR seems to make the blit docs significantly longer, when part of the issue being brought up by OP was the docs being too long and overcomplicated for entry level users. I'm not sure how you'd like to tackle this in PRs.

[itzpr3d4t0r]

I don't find these docs too overcomplicated, maybe a bit too long still but mind that writing docs isn't an easy task, as is demonstrated by how poorly our docs are written (my fblits docs as well). With this PR I think I added a lot more information that wasn't even there before, and organised it in a way in which if you're a beginner you can simply read the first 6 lines and you are fine but if you're an advanced user you can go more in-depth further down. Sorry but aside from it beeing a bit too long and the possibility of making a separate page for special flags i just don't see how these docs are bad. They are better structured, have a clear begginner at the top and advanced at the bottom structure, add meaningful information that you could've only gotten with errors/debug.

[Starbuck5]

Went over this a bit again.

• Weird to have a bulleted list followed by 4 paragraphs explaining in further detail. All the detail could be in the bulleted list of parameters in the first place.
• Lets do a separate page for the flags, like color_list
• The notes section needs to get restructured, because the notes all look very high importance, but they're not that important. I suggested having them as a paragraph of bits and bobs after the list of parameters.

[Starbuck5]

Rather than referencing a class and then referencing a method, you could just reference Surface.premul_alpha directly.

[Starbuck5]

So now the list of parameters is not a bulleted list at all, which looks weird to me. The pygame functions usually have a bulleted list of parameters (draw) or paragraphs.

There is now a bulleted list of notes, which is better than before. But it's just weird that almost all the notes directly map to one parameter. Like why not have the information in the parameter descriptions?

[MyreMylar]

Looks good over all - I added a couple of small suggestions.

Thanks for the hard work on this 👍

[MyreMylar]

Looks like this one needs a merge with main to clear the CircleCI fail.

Outdated review and reviewer wasn't active for a long time