Repository navigation
Improving Unsafe Code Documentation in the Rust Standard Library #640
Description
| Metadata | |
|---|---|
| Contact | @hxuhack |
| Team(s) | libs, opsem |
| Goal document | 2026/improve-std-unsafe |
Summary
Review unsafe code documentation in the Rust standard library, identify inconsistencies, and fix them. Based on the lessons learned during this review process, we also aim to establish explicit conventions for code safety reasoning and unsafe code documentation.
This issue is intended for status updates only.
For general questions or comments, please contact a goal owner or post in the Zulip topic.
Activity
tomassedovic commentedon May 5, 2026
This issue is intended for status updates only.
For general questions or comments, please contact the owner(s) directly.
hxuhack commentedon May 6, 2026
We have built a website that continuously tracks the safety doc of unsafe APIs in the standard library. Our effort starts with non-intrinsic unsafe APIs, aiming to ensure that all such APIs are equipped with explicit safety sections as a first step.
hxuhack commentedon Jun 29, 2026
Trying to fix all methods without safety docs. Currently, there are 55/643 left. Some of these methods implement the same traits, so we only need to add safety docs to the trait methods and can then obtain the safety docs from the traits.
Currently, the main challenge is that adding some safety docs involves ACP (154665), even when the change only duplicates existing sentences or makes minor syntax adjustments. See 158383.
hxuhack commentedon Aug 28, 2026
The following PRs have been submitted and merged since July as part of this effort:
hxuhack commentedon Sep 25, 2026
The following PRs have been submitted during the past month:
Since text duplication is a major concern for some unsafe APIs that currently do not have safety documentation, we have proposed ACP: Referencing existing safety contracts in unsafe API documentation. The ACP is currently under review.
hxuhack commentedon Oct 12, 2026
Current Results (based on nightly-2026-10-11)
Overall, unsafe APIs in the Rust standard library fall into four categories.
Free functions: There are 5,159 free functions, of which 3,106 have no
# Safetysection.Of these, 3,006 are in the
core::archmodule.hexagon: 1,853/1,853 APIs.x86: 544/559 APIs.s390x: 196/196 APIs.powerpc: 118/118 APIs.x86_64: 75/75 APIs.riscv_shared: 38/38 APIs.loongarch64: 34/34 APIs.Some architectures have more standardized safety documentation:
aarch64: Only 13 of 1,411 unsafe functions lack a# Safetysection. However, more than 200neonAPIs are documented only with the generic statementNeon intrinsic unsafe.arm_shared: Only 3 of 550 unsafe functions lack a# Safetysection. However, 547neonAPIs are documented only with the generic statementNeon intrinsic unsafe.Methods: There are 506 methods, excluding trait method implementations, of which 40 have no
# Safetysection. But, most of them already refer to other methods with the same safety requirements.Trait methods: Ideally, the safety requirements of unsafe methods declared in a trait should be documented at the trait definition rather than separately at each implementation site. This is because the safety requirements should be the same regardless of the type implementing the trait. There are 25 such unsafe methods, of which 2 have no
# Safetysection.Unsafe traits: There are 28 unsafe traits, of which 9 have no safety documentation. Ideally, each unsafe trait should document its safety requirements, which specify the invariants that implementors must uphold.
Conclusion and Future Work