Clean Surface docs 2: Rewrite object, convert, flags docstrings

[damusss]

I'm splitting #3455 . This PR contains the four docstrings that are closely related to surface format internals and that have been rewritten almost entirely, requiring more attention.

[coderabbitai]

📝 Walkthrough

Walkthrough

Rewrote and expanded the Surface stub docstrings in buildconfig/stubs/pygame/surface.pyi to clarify surface creation and format selection, transparency types and interactions, locking/pixel-access rules, convert/convert_alpha semantics (including pygame.error when display is uninitialized), and current flag descriptions. No API/signature changes.

Changes

Cohort / File(s)

Summary of Changes

Pygame Surface stub doc updates buildconfig/stubs/pygame/surface.pyi

Rewrote and expanded Surface docstrings: consolidated surface creation/format-selection guidance (size-only, masks/flags, other Surface, or bit depth + masks); enumerated transparency types (per-pixel, premultiplied, global alpha, colorkey) and interaction/performance rules; updated locking/pixel-access guidance and subsurface notes; detailed convert and convert_alpha behavior including pygame.error when display is uninitialized; replaced legacy flag descriptions with current enumerated flags and marked obsolete/internal flags; wording/formatting refinements. No signature/API changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Clean Surface docs 3: minor clarifications, typos and movements #3605 — Overlapping edits to buildconfig/stubs/pygame/surface.pyi, touching Surface docstrings and pixel/locking notes.

Suggested reviewers

• Starbuck5
• ankith26
• aatle

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly describes the main change: rewriting docstrings for Surface object, convert methods, and flags documentation.
Description check	✅ Passed	The description explains that this PR splits a larger PR and focuses on four closely-related docstrings about surface format internals that require attention.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 963fef1 and 713eaea.

📒 Files selected for processing (1)

• buildconfig/stubs/pygame/surface.pyi (3 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

buildconfig/stubs/pygame/surface.pyi (1)

src_py/__init__.py (1)

• Surface (227-228)

🔇 Additional comments (4)

buildconfig/stubs/pygame/surface.pyi (4)

49-89: Excellent documentation improvements.

The rewritten Surface class docstring significantly improves clarity:

• Clear explanation of Surface creation behavior (lines 49-53)
• Well-structured enumeration of format control methods (lines 55-66)
• Comprehensive coverage of transparency types (lines 78-89)
• Helpful guidance on pixel access and performance (lines 99-114)

The new structure makes the documentation much more accessible for users.

Also applies to: 94-115

---

289-315: Clear and comprehensive convert() documentation.

The rewritten docstring effectively explains the multiple ways to control pixel format conversion:

• No-argument form (display format matching)
• Surface-based format copying
• Bit depth and flags specification
• Bitmask-based control

The documentation of the pygame.error exception (lines 298-299, 327) when the display Surface is uninitialized is a valuable addition for users.

Consider verifying the pygame.error behavior by checking the actual implementation or testing, though this appears consistent with standard pygame behavior.

---

317-330: Improved convert_alpha() clarity.

The updated documentation better explains the optimization trade-off: the resulting surface format is tailored for fast alpha blitting rather than exactly matching the display format. This is an important distinction for users to understand.

---

797-813: Well-organized flag documentation.

The restructured flag listing improves usability:

• Clear enumeration of current flags with descriptions (lines 798-804)
• Explicit reference to display-specific flags (lines 806-807)
• Separated obsolete flags section for historical reference (lines 809-812)

This organization makes it easier for users to understand which flags are relevant for their use cases.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

buildconfig/stubs/pygame/surface.pyi (3)

55-55: Minor grammar improvement.

The phrase "is providing" could be more idiomatic as "is by providing" or "is to provide".

Apply this diff:

-One way to control the pixel format/characteristics is providing a bitmask of flags:
+One way to control the pixel format/characteristics is by providing a bitmask of flags:

---

111-111: Simplify awkward formatting.

The phrase "lock()'ed" uses awkward formatting. Consider using "locked" for better readability.

Apply this diff:

-    Any functions that directly access a Surface's pixel data will need that
-    Surface to be lock()'ed in some cases. Built in functions that manipulate
+    Any functions that directly access a Surface's pixel data will need that
+    Surface to be locked in some cases. Built-in functions that manipulate
     Surfaces will lock and unlock the Surface automatically. Only use manual

Note: Also corrected "Built in" to "Built-in" for consistency.

---

306-307: Improve informal phrasing.

The phrase "calculated wrong" is informal. Use "incorrectly calculated" or "miscalculated" for more professional documentation.

Apply this diff:

-           * Passing the bitmasks of the pixels and flags. Note that the bit depth
-             could be calculated wrong, therefore it is not advised to use this
-             path as it might be deprecated in the future.
+           * Passing the bitmasks of the pixels and flags. Note that the bit depth
+             could be incorrectly calculated, therefore it is not advised to use this
+             approach as it might be deprecated in the future.

Note: Also changed "this path" to "this approach" for clarity.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1d063a8 and ee4614c.

📒 Files selected for processing (1)

• buildconfig/stubs/pygame/surface.pyi (4 hunks)

🔇 Additional comments (2)

buildconfig/stubs/pygame/surface.pyi (2)

320-327: LGTM!

The convert_alpha() docstring clearly explains that the result is optimized for alpha blitting rather than matching the display format exactly, and correctly uses "raised" for the exception. The documentation accurately describes the behavior and constraints.

---

797-813: LGTM!

The get_flags() docstring provides a comprehensive and well-organized list of flags, clearly distinguishing between active, private, and obsolete flags. The explicit examples of obsolete flags help developers understand which features are no longer relevant in pygame 2.