rustdoc: implement RFC 3842 with safety::requires attribute

* Support "#[safety::requires()]" attribute for documentation injection.
* Support "{Tag}={description}" format with customized tags.
* Prototype implementation of Safety contract insertion.

Author: yilin0518

Cargo.lock

@@ -4885,6 +4885,7 @@ dependencies = [
  "stringdex",
  "tempfile",
  "threadpool",
+ "toml 0.8.23",
  "tracing",
  "tracing-subscriber",
  "tracing-tree",

library/core/src/lib.rs

@@ -157,6 +157,7 @@
 #![feature(optimize_attribute)]
 #![feature(pattern_types)]
 #![feature(prelude_import)]
+#![feature(register_tool)]
 #![feature(repr_simd)]
 #![feature(rustc_attrs)]
 #![feature(rustdoc_internals)]
@@ -192,6 +193,9 @@
 #![feature(x86_amx_intrinsics)]
 // tidy-alphabetical-end
 
+// Inert attributes for rustdoc `inject-safety-docs` (`--safety-spec`); see `safety::requires`.
+#![register_tool(safety)]
+
 // allow using `core::` in intra-doc links
 #[allow(unused_extern_crates)]
 extern crate self as core;

library/core/src/ptr/mod.rs

@@ -1729,12 +1729,6 @@ pub const unsafe fn read<T>(src: *const T) -> T {
 ///
 /// # Safety
 ///
-/// Behavior is undefined if any of the following conditions are violated:
-///
-/// * `src` must be [valid] for reads.
-///
-/// * `src` must point to a properly initialized value of type `T`.
-///
 /// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of
 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned
 /// value and the value at `*src` can [violate memory safety][read-ownership].
@@ -1797,6 +1791,7 @@ pub const unsafe fn read<T>(src: *const T) -> T {
 #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]
 #[track_caller]
 #[rustc_diagnostic_item = "ptr_read_unaligned"]
+#[safety::requires(ValidPtrRead(src, T, 1), Init(src, T))]
 pub const unsafe fn read_unaligned<T>(src: *const T) -> T {
     let mut tmp = MaybeUninit::<T>::uninit();
     // SAFETY: the caller must guarantee that `src` is valid for reads.

src/bootstrap/src/core/build_steps/doc.rs

@@ -813,6 +813,15 @@ fn doc_std(
         .rustdocflag("--extern-html-root-takes-precedence")
         .rustdocflag("--resource-suffix")
         .rustdocflag(&builder.version);
+    let safety_spec_in_rustdocflags =
+        env::var("RUSTDOCFLAGS").map(|s| s.contains("--safety-spec")).unwrap_or(false);
+    // If `--safety-spec` is not set in `RUSTDOCFLAGS`, set it to the default spec file.
+    if !safety_spec_in_rustdocflags {
+        let safety_spec_path = builder.src.join("src/librustdoc/assets/sp-core.toml");
+        if let Some(p) = safety_spec_path.to_str() {
+            cargo.rustdocflag("--safety-spec").rustdocflag(p);
+        }
+    }
     for arg in extra_args {
         cargo.rustdocflag(arg);
     }

src/librustdoc/Cargo.toml

@@ -25,6 +25,7 @@ smallvec = "1.8.1"
 stringdex = "=0.0.6"
 tempfile = "3"
 threadpool = "1.8.1"
+toml = "0.8"
 tracing = "0.1"
 tracing-tree = "0.3.0"
 unicode-segmentation = "1.9"

src/librustdoc/assets/sp-core.toml

@@ -0,0 +1,9 @@
+package.name = "core"
+
+[tag.ValidPtrRead]
+args = [ "p", "T", "len" ]
+desc = "pointer `{p}` must be [valid](crate::ptr#safety) for reading the `sizeof({T})*{len}` memory from it."
+
+[tag.Init]
+args = [ "p", "T" ]
+desc = "`{p}` must point to a properly initialized value of type `{T}`."

src/librustdoc/config.rs

@@ -312,6 +312,8 @@ pub(crate) struct RenderOptions {
     pub(crate) disable_minification: bool,
     /// If `true`, HTML source pages will generate the possibility to expand macros.
     pub(crate) generate_macro_expansion: bool,
+    /// Optional TOML spec for `inject-safety-docs` (`#[safety::requires]`).
+    pub(crate) safety_spec: Option<PathBuf>,
 }
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
@@ -852,6 +854,8 @@ impl Options {
 
         let disable_minification = matches.opt_present("disable-minification");
 
+        let safety_spec = matches.opt_str("safety-spec").map(PathBuf::from);
+
         let options = Options {
             bin_crate,
             proc_macro_crate,
@@ -930,6 +934,7 @@ impl Options {
             include_parts_dir,
             parts_out_dir,
             disable_minification,
+            safety_spec,
         };
         Some((input, options, render_options, loaded_paths))
     }

src/librustdoc/core.rs

@@ -11,7 +11,7 @@ use rustc_errors::emitter::{DynEmitter, HumanReadableErrorType, OutputTheme, std
 use rustc_errors::json::JsonEmitter;
 use rustc_feature::UnstableFeatures;
 use rustc_hir::def::Res;
-use rustc_hir::def_id::{DefId, DefIdMap, DefIdSet, LocalDefId};
+use rustc_hir::def_id::{DefId, DefIdMap, DefIdSet, LOCAL_CRATE, LocalDefId};
 use rustc_hir::intravisit::{self, Visitor};
 use rustc_hir::{HirId, Path};
 use rustc_lint::{MissingDoc, late_lint_mod};
@@ -68,6 +68,8 @@ pub(crate) struct DocContext<'tcx> {
     pub(crate) output_format: OutputFormat,
     /// Used by `strip_private`.
     pub(crate) show_coverage: bool,
+    /// Used by `inject-safety-docs` to transform `#[safety::requires]` into documentation text.
+    pub(crate) safety_spec: Option<Arc<crate::passes::inject_safety_docs::SafetySpec>>,
 }
 
 impl<'tcx> DocContext<'tcx> {
@@ -359,6 +361,14 @@ pub(crate) fn run_global_ctxt(
     let auto_traits =
         tcx.visible_traits().filter(|&trait_def_id| tcx.trait_is_auto(trait_def_id)).collect();
 
+    let safety_spec = render_options.safety_spec.as_ref().and_then(|path| {
+        crate::passes::inject_safety_docs::load_safety_spec(
+            path,
+            tcx.crate_name(LOCAL_CRATE).as_str(),
+            tcx.dcx(),
+        )
+    });
+
     let mut ctxt = DocContext {
         tcx,
         param_env: ParamEnv::empty(),
@@ -373,6 +383,7 @@ pub(crate) fn run_global_ctxt(
         inlined: FxHashSet::default(),
         output_format,
         show_coverage,
+        safety_spec,
     };
 
     for cnum in tcx.crates(()) {

src/librustdoc/lib.rs

@@ -562,6 +562,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "Include the memory layout of types in the docs",
             "",
         ),
+        opt(
+            Unstable,
+            Opt,
+            "",
+            "safety-spec",
+            "transform the safety specification into the documentation from the given TOML file or literal string",
+            "PATH",
+        ),
         opt(Unstable, Flag, "", "no-capture", "Don't capture stdout and stderr of tests", ""),
         opt(
             Unstable,