Clean Surface docs 1: Capitalize surface/surfaces

[damusss]

I'm splitting #3455 and there I capitalized Surface and Surfaces. The current docs used lowercase and capitalization randomly without consistency so I picked a side and made all instances conform.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated type-stub method signatures in buildconfig/stubs/pygame/surface.pyi for the Surface class, renaming parameter identifiers from surface to Surface in the __init__ and convert overloads. No implementation or documentation content changed; only public declaration signatures were modified.

Changes

Cohort / File(s)	Summary of Changes
Pygame Surface stub signature updates buildconfig/stubs/pygame/surface.pyi	Renamed parameter identifier surface → Surface in Surface.__init__ overload and Surface.convert overload; no logic or docs altered; public type signatures only.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly identifies the primary change by indicating a Surface documentation cleanup focused on capitalizing “surface/surfaces,” and it is concise and specific enough that teammates can understand the main purpose at a glance.
Description Check	✅ Passed	The description directly relates to the documented changes by explaining that this PR splits a previous one and consistently capitalizes “Surface” and “Surfaces” across the documentation, matching the summary of edits.
Docstring Coverage	✅ Passed	Docstring coverage is 92.31% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent 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 351cf76 and ffca96e.

⛔ Files ignored due to path filters (1)

• src_c/doc/surface_doc.h is excluded by !src_c/doc/*

📒 Files selected for processing (1)

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

🧰 Additional context used

🧬 Code graph analysis (1)

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

src_py/__init__.py (1)

• Surface (227-228)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: x86
• GitHub Check: aarch64
• GitHub Check: Debian (Bookworm - 12) [ppc64le]
• GitHub Check: Debian (Bookworm - 12) [armv6]
• GitHub Check: build (ubuntu-22.04)

🔇 Additional comments (1)

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

56-1025: LGTM! Documentation consistency improvements look good.

All the capitalization changes appropriately refer to the pygame Surface class and improve documentation consistency. The changes correctly:

1. Capitalize Surface/Surfaces when referring to the pygame class or its instances
2. Keep parameter names lowercase (e.g., surface: Surface at lines 135, 286) per Python naming conventions
3. Only modify documentation text without changing any functional code

The previous review concerns about parameter names shadowing the class name have been properly addressed.

---

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

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

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

130-136: Parameter name shadows class name.

The parameter name Surface shadows the class name Surface, violating Python naming conventions and creating confusion. Parameter names should be lowercase (e.g., surface) to distinguish them from type names.

Additionally, this change appears inconsistent with the PR objective, which states the goal is to capitalize "Surface" in documentation, not in method signatures.

Apply this diff to fix the parameter naming:

     @overload
     def __init__(
         self,
         size: Point,
         flags: int = 0,
-        Surface: Surface = ...,
+        surface: Surface = ...,
     ) -> None: ...

📜 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 351cf76.

⛔ Files ignored due to path filters (1)

• src_c/doc/surface_doc.h is excluded by !src_c/doc/*

📒 Files selected for processing (1)

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

🧰 Additional context used

🧬 Code graph analysis (1)

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

src_py/__init__.py (1)

• Surface (227-228)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (19)

• GitHub Check: x86_64
• GitHub Check: x86_64
• GitHub Check: aarch64
• GitHub Check: debug_coverage (ubuntu-24.04, 3.9.23)
• GitHub Check: debug_coverage (ubuntu-24.04, 3.14.0rc1)
• GitHub Check: debug_coverage (ubuntu-24.04, 3.13.5)
• GitHub Check: build (ubuntu-24.04)
• GitHub Check: build (windows-latest)
• GitHub Check: build (macos-14)
• GitHub Check: x86
• GitHub Check: AMD64
• GitHub Check: Debian (Bookworm - 12) [s390x]
• GitHub Check: dev-check
• GitHub Check: Debian (Bookworm - 12) [armv6]
• GitHub Check: Debian (Bookworm - 12) [armv7]
• GitHub Check: Debian (Bookworm - 12) [ppc64le]
• GitHub Check: msys2 (mingw64, x86_64)
• GitHub Check: msys2 (ucrt64, ucrt-x86_64)
• GitHub Check: msys2 (clang64, clang-x86_64)