1
Fork 0

Reflow MirPhase comments.

Currently many of them exceed 100 chars, which makes them painful to
read on a terminal that is 100 chars wide.
This commit is contained in:
Nicholas Nethercote 2025-02-18 14:16:22 +11:00
parent 5986ff05d8
commit c9fbaab453

View file

@ -53,7 +53,8 @@ pub enum MirPhase {
/// sequences of statements that would generally be subject to constant promotion are /// sequences of statements that would generally be subject to constant promotion are
/// semantically constants, while in analysis MIR all constants are explicit. /// semantically constants, while in analysis MIR all constants are explicit.
/// ///
/// The result of const promotion is available from the `mir_promoted` and `promoted_mir` queries. /// The result of const promotion is available from the `mir_promoted` and `promoted_mir`
/// queries.
/// ///
/// This is the version of MIR used by borrowck and friends. /// This is the version of MIR used by borrowck and friends.
Analysis(AnalysisPhase), Analysis(AnalysisPhase),
@ -61,26 +62,27 @@ pub enum MirPhase {
/// ///
/// The semantic changes that occur in the lowering from analysis to runtime MIR are as follows: /// The semantic changes that occur in the lowering from analysis to runtime MIR are as follows:
/// ///
/// - Drops: In analysis MIR, `Drop` terminators represent *conditional* drops; roughly speaking, /// - Drops: In analysis MIR, `Drop` terminators represent *conditional* drops; roughly
/// if dataflow analysis determines that the place being dropped is uninitialized, the drop will /// speaking, if dataflow analysis determines that the place being dropped is uninitialized,
/// not be executed. The exact semantics of this aren't written down anywhere, which means they /// the drop will not be executed. The exact semantics of this aren't written down anywhere,
/// are essentially "what drop elaboration does." In runtime MIR, the drops are unconditional; /// which means they are essentially "what drop elaboration does." In runtime MIR, the drops
/// when a `Drop` terminator is reached, if the type has drop glue that drop glue is always /// are unconditional; when a `Drop` terminator is reached, if the type has drop glue that
/// executed. This may be UB if the underlying place is not initialized. /// drop glue is always executed. This may be UB if the underlying place is not initialized.
/// - Packed drops: Places might in general be misaligned - in most cases this is UB, the exception /// - Packed drops: Places might in general be misaligned - in most cases this is UB, the
/// is fields of packed structs. In analysis MIR, `Drop(P)` for a `P` that might be misaligned /// exception is fields of packed structs. In analysis MIR, `Drop(P)` for a `P` that might be
/// for this reason implicitly moves `P` to a temporary before dropping. Runtime MIR has no such /// misaligned for this reason implicitly moves `P` to a temporary before dropping. Runtime
/// rules, and dropping a misaligned place is simply UB. /// MIR has no such rules, and dropping a misaligned place is simply UB.
/// - Unwinding: in analysis MIR, unwinding from a function which may not unwind aborts. In runtime /// - Unwinding: in analysis MIR, unwinding from a function which may not unwind aborts. In
/// MIR, this is UB. /// runtime MIR, this is UB.
/// - Retags: If `-Zmir-emit-retag` is enabled, analysis MIR has "implicit" retags in the same way /// - Retags: If `-Zmir-emit-retag` is enabled, analysis MIR has "implicit" retags in the same
/// that Rust itself has them. Where exactly these are is generally subject to change, and so we /// way that Rust itself has them. Where exactly these are is generally subject to change,
/// don't document this here. Runtime MIR has most retags explicit (though implicit retags /// and so we don't document this here. Runtime MIR has most retags explicit (though implicit
/// can still occur at `Rvalue::{Ref,AddrOf}`). /// retags can still occur at `Rvalue::{Ref,AddrOf}`).
/// - Coroutine bodies: In analysis MIR, locals may actually be behind a pointer that user code has /// - Coroutine bodies: In analysis MIR, locals may actually be behind a pointer that user code
/// access to. This occurs in coroutine bodies. Such locals do not behave like other locals, /// has access to. This occurs in coroutine bodies. Such locals do not behave like other
/// because they eg may be aliased in surprising ways. Runtime MIR has no such special locals - /// locals, because they eg may be aliased in surprising ways. Runtime MIR has no such
/// all coroutine bodies are lowered and so all places that look like locals really are locals. /// special locals. All coroutine bodies are lowered and so all places that look like locals
/// really are locals.
/// ///
/// Also note that the lint pass which reports eg `200_u8 + 200_u8` as an error is run as a part /// Also note that the lint pass which reports eg `200_u8 + 200_u8` as an error is run as a part
/// of analysis to runtime MIR lowering. To ensure lints are reported reliably, this means that /// of analysis to runtime MIR lowering. To ensure lints are reported reliably, this means that
@ -111,7 +113,8 @@ pub enum AnalysisPhase {
/// * [`TerminatorKind::FalseEdge`] /// * [`TerminatorKind::FalseEdge`]
/// * [`StatementKind::FakeRead`] /// * [`StatementKind::FakeRead`]
/// * [`StatementKind::AscribeUserType`] /// * [`StatementKind::AscribeUserType`]
/// * [`StatementKind::Coverage`] with [`CoverageKind::BlockMarker`] or [`CoverageKind::SpanMarker`] /// * [`StatementKind::Coverage`] with [`CoverageKind::BlockMarker`] or
/// [`CoverageKind::SpanMarker`]
/// * [`Rvalue::Ref`] with `BorrowKind::Fake` /// * [`Rvalue::Ref`] with `BorrowKind::Fake`
/// * [`CastKind::PointerCoercion`] with any of the following: /// * [`CastKind::PointerCoercion`] with any of the following:
/// * [`PointerCoercion::ArrayToPointer`] /// * [`PointerCoercion::ArrayToPointer`]