Skip to content

Stop Rust comments on Python items from becoming __doc__ - #8893

Merged
youknowone merged 1 commit into
RustPython:mainfrom
youknowone:py-item-comments
Sep 28, 2026
Merged

Stop Rust comments on Python items from becoming __doc__#8893
youknowone merged 1 commit into
RustPython:mainfrom
youknowone:py-item-comments

Conversation

@youknowone

@youknowone youknowone commented Sep 28, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Member

Rust /// comments on #[py*] items are published as __doc__. This changes them to // where the text is a Rust implementation note rather than a Python docstring, so these objects no longer show it:

  • weakref.ReferenceType ("PyWeakReference: …"), types.FrameType, types.WrapperDescriptorType, types.MethodWrapperType, types.ClassMethodDescriptorType
  • _io.FileIO._dealloc_warn ("fileio_dealloc_warn in Modules/_io/fileio.c")
  • _pickle.Pickler.persistent_id, _pickle.Unpickler.persistent_load
  • _ctypes.PyObj_FromPtr, _unpickle, call_function, call_cdeclfunction, _SimpleCData.__ctypes_from_outparam__
  • _multibytecodec.__create_codec, _multiprocessing.SemLock._rebuild, _multiprocessing.sem_unlink, _ssl._test_decode_cert
  • the same kind of comments in _asyncio, _elementtree, _json, resource, _abc, gc, _winapi, _interpchannels and the wasm _js module

Where the database has a docstring for the item, that is now used instead (weakref.ReferenceType.__class_getitem__).

Only comments change. rustdoc on items that are not exposed to Python is unchanged. /// that matches the real docstring (struct sequence __replace__, coroutine.__name__/__qualname__) is left for #8877, which provides the database entries for them.

Checked with a __doc__ dump over every builtin module's classes, functions and descriptors against CPython 3.14.7 (macOS arm64): 18 more items match than on main (908368e), none fewer.

Split out of #8877.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Updated internal explanatory notes across several areas of the project. These changes do not affect application behavior, available features, or the information shown to users. No user-facing changes are included in this release.

@youknowone
Stop Rust comments on Python items from becoming __doc__
648427e 
Use `//` instead of `///` on Python-exposed items so their comments are not
published as `__doc__`.

Assisted-by: Claude:claude-opus-5-5
Assisted-by: Grok:grok-4.7
@youknowone youknowone mentioned this pull request Sep 28, 2026
Merged
@coderabbitai

coderabbitai Bot commented Sep 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: RustPython/RustPython/.coderabbit.yml

Review profile: CHILL

Plan: Advanced

Run ID: 66097953-1eac-4255-bc4f-022a5550a534

📥 Commits

Reviewing files that changed from the base of the PR and between cc8b4d4 and 648427e.

📒 Files selected for processing (27)
  • crates/stdlib/src/_asyncio.rs
  • crates/stdlib/src/cjkcodecs/multibytecodec.rs
  • crates/stdlib/src/elementtree.rs
  • crates/stdlib/src/json.rs
  • crates/stdlib/src/multiprocessing.rs
  • crates/stdlib/src/pickle.rs
  • crates/stdlib/src/resource.rs
  • crates/stdlib/src/ssl.rs
  • crates/vm/src/builtins/asyncgenerator.rs
  • crates/vm/src/builtins/descriptor.rs
  • crates/vm/src/builtins/object.rs
  • crates/vm/src/exceptions.rs
  • crates/vm/src/frame.rs
  • crates/vm/src/object/core.rs
  • crates/vm/src/stdlib/_abc.rs
  • crates/vm/src/stdlib/_ctypes.rs
  • crates/vm/src/stdlib/_ctypes/array.rs
  • crates/vm/src/stdlib/_ctypes/function.rs
  • crates/vm/src/stdlib/_ctypes/pointer.rs
  • crates/vm/src/stdlib/_ctypes/simple.rs
  • crates/vm/src/stdlib/_ctypes/structure.rs
  • crates/vm/src/stdlib/_ctypes/union.rs
  • crates/vm/src/stdlib/_interpchannels.rs
  • crates/vm/src/stdlib/_io.rs
  • crates/vm/src/stdlib/_winapi.rs
  • crates/vm/src/stdlib/gc.rs
  • crates/wasm/src/js_module.rs

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

Walkthrough

Comments across Rust standard-library, VM, and WebAssembly modules were changed or reworded. The PyWeakReference class annotation now sets its Python-visible name to ReferenceType and its module to weakref.

Changes

Source comments and annotations

Layer / File(s) Summary
Standard-library comment updates
crates/stdlib/src/*		 Comments in standard-library modules were converted to ordinary comments or reworded. The described implementations and declarations remain unchanged.
VM and WebAssembly comment updates
crates/vm/src/builtins/*, crates/vm/src/exceptions.rs, crates/vm/src/frame.rs, crates/vm/src/stdlib/*, crates/wasm/src/js_module.rs		 Comments in VM and WebAssembly modules were converted to ordinary comments or reworded. Implementations remain unchanged.
Weak-reference class annotation
crates/vm/src/object/core.rs		 The PyWeakReference class annotation sets the Python-visible name to ReferenceType and the module to weakref.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: joshuamegnauth54

Merge Risk: ⚪ Minimal · up to 64842

The comment updates leave behavior unchanged, and the weak-reference class metadata matches its exported name and module. No actionable merge-blocking risk is identified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 64842

The weak-reference type’s visible name and module change, which may affect code that inspects them. No change to executable behavior or privileges was identified, but downstream compatibility has not been verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The identified public-contract exposure is to consumers inspecting the weak-reference type and affected doc values; no expanded executable entrypoint is established by the reviewed changes.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the main change: preventing Rust comments on Python-exposed items from becoming doc values.
Docstring Coverage ✅ Passed Docstring coverage is 88.61% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 79 functions across 26 files. (1 skipped: 1…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR

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

Comment @coderabbitai help to get the list of available commands.

@youknowone
youknowone merged commit 4344a34 into RustPython:main Sep 28, 2026
9 checks passed
@youknowone
youknowone deleted the py-item-comments branch September 28, 2026 15:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@youknowone