Improving Unsafe Code Documentation in the Rust Standard Library

[tomassedovic]

Metadata
Point of 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.

Tasks and status

---

Note: we have updated the body to match the 2026 goal. Your original text is preserved below.

Details

Metadata
Point of 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.

Tasks and status

[tomassedovic]

This issue is intended for status updates only.

For general questions or comments, please contact the owner(s) directly.

[hxuhack]

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]

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]

The following PRs have been submitted and merged since July as part of this effort:

Pull Request	API	Info	Contributor
158810	*const[T]::get_unchecked, NonNull<[T]>::get_unchecked_mut	Add supplementary information	yilin0518
2183	_mm_stream_si32, _mm_stream_si64	Add supplementary information	yilin0518
158804	*mut T::as_uninit_mut	Add supplementary information	yilin0518
159322	intrinsic::simd::simd_gather, intrinsic::simd::simd_scatter	Fix safety section	yilin0518
159402	intrinsic::simd::simd_shl/shr, intrinsic::simd::simd_funnel_shl/shr, intrinsic::simd::simd_masked_load, intrinsic::simd::simd_masked_store	Fix safety section	yilin0518
161271	CodePoint::from_u32_unchecked, Wtf8::from_bytes_unchecked, Wtf8::from_mut_bytes_unchecked	Add safety section	yilin0518
161292	alloc::Wtf8	Add safety section and discharge	yilin0518