From 5075931290ac4939b1645d2a9cde06cce240ba59 Mon Sep 17 00:00:00 2001
From: Alona Enraght-Moony <code@alona.page>
Date: Tue, 2 Apr 2024 22:46:00 +0000
Subject: [PATCH] rustc_ast: Update `P<T>` docs to reflect mutable status.
`P<T>` has implemented `DerefMut` since #54277. While this was lamented
at the time [1], rustc now relies on it extensively via the many
implementors of MutVisitor [2].
Updates the docs to reflect that `P<T>` is fundamentally mutable, and a
few other cleanups to make them nicer to browse.
[1]: https://github.com/rust-lang/rust/pull/54277#discussion_r257181754
[2]: https://doc.rust-lang.org/1.77.1/nightly-rustc/rustc_ast/mut_visit/trait.MutVisitor.html#implementors
---
compiler/rustc_ast/src/ptr.rs | 16 +++++++---------
1 file changed, 7 insertions(+), 9 deletions(-)
diff --git a/compiler/rustc_ast/src/ptr.rs b/compiler/rustc_ast/src/ptr.rs
index 0140fb752bf..e22a523dbc3 100644
--- a/compiler/rustc_ast/src/ptr.rs
+++ b/compiler/rustc_ast/src/ptr.rs
@@ -1,6 +1,6 @@
//! The AST pointer.
//!
-//! Provides `P<T>`, a frozen owned smart pointer.
+//! Provides [`P<T>`][struct@P], an owned smart pointer.
//!
//! # Motivations and benefits
//!
@@ -8,18 +8,14 @@
//! passes (e.g., one may be able to bypass the borrow checker with a shared
//! `ExprKind::AddrOf` node taking a mutable borrow).
//!
-//! * **Immutability**: `P<T>` disallows mutating its inner `T`, unlike `Box<T>`
-//! (unless it contains an `Unsafe` interior, but that may be denied later).
-//! This mainly prevents mistakes, but also enforces a kind of "purity".
-//!
//! * **Efficiency**: folding can reuse allocation space for `P<T>` and `Vec<T>`,
//! the latter even when the input and output types differ (as it would be the
//! case with arenas or a GADT AST using type parameters to toggle features).
//!
-//! * **Maintainability**: `P<T>` provides a fixed interface - `Deref`,
-//! `and_then` and `map` - which can remain fully functional even if the
-//! implementation changes (using a special thread-local heap, for example).
-//! Moreover, a switch to, e.g., `P<'a, T>` would be easy and mostly automated.
+//! * **Maintainability**: `P<T>` provides an interface, which can remain fully
+//! functional even if the implementation changes (using a special thread-local
+//! heap, for example). Moreover, a switch to, e.g., `P<'a, T>` would be easy
+//! and mostly automated.
use std::fmt::{self, Debug, Display};
use std::ops::{Deref, DerefMut};
@@ -29,6 +25,8 @@ use rustc_serialize::{Decodable, Decoder, Encodable, Encoder};
use rustc_data_structures::stable_hasher::{HashStable, StableHasher};
/// An owned smart pointer.
+///
+/// See the [module level documentation][crate::ptr] for details.
pub struct P<T: ?Sized> {
ptr: Box<T>,
}