Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 07cb420

Browse files
Some hygiene doc improvements
1 parent 154037f commit 07cb420

File tree

2 files changed

+25
-10
lines changed

2 files changed

+25
-10
lines changed

‎compiler/rustc_span/src/hygiene.rs

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,12 @@ use crate::symbol::{Symbol, kw, sym};
4646
use crate::{DUMMY_SP, HashStableContext, Span, SpanDecoder, SpanEncoder, with_session_globals};
4747

4848
/// A `SyntaxContext` represents a chain of pairs `(ExpnId, Transparency)` named "marks".
49+
///
50+
/// This can generally be thought of as the macro call stack for a given location in code.
51+
/// Although, when a macro emits code from input parameters, that emitted code retains its
52+
/// call-site SyntaxContext.
53+
///
54+
/// See <https://rustc-dev-guide.rust-lang.org/macro-expansion.html> for more explanation.
4955
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
5056
pub struct SyntaxContext(u32);
5157

@@ -61,7 +67,10 @@ pub type SyntaxContextKey = (SyntaxContext, ExpnId, Transparency);
6167

6268
#[derive(Clone, Copy, Debug)]
6369
struct SyntaxContextData {
70+
/// The last macro expansion.
71+
/// (Here we say the most deeply nested macro expansion is the "outermost" expansion.)
6472
outer_expn: ExpnId,
73+
/// Transparency of the last macro expansion
6574
outer_transparency: Transparency,
6675
parent: SyntaxContext,
6776
/// This context, but with all transparent and semi-opaque expansions filtered away.
@@ -450,11 +459,13 @@ impl HygieneData {
450459
self.syntax_context_data[ctxt.0 as usize].opaque_and_semiopaque
451460
}
452461

462+
/// See [`SyntaxContextData::outer_expn`]
453463
#[inline]
454464
fn outer_expn(&self, ctxt: SyntaxContext) -> ExpnId {
455465
self.syntax_context_data[ctxt.0 as usize].outer_expn
456466
}
457467

468+
/// The last macro expansion and its Transparency
458469
#[inline]
459470
fn outer_mark(&self, ctxt: SyntaxContext) -> (ExpnId, Transparency) {
460471
let data = &self.syntax_context_data[ctxt.0 as usize];
@@ -900,6 +911,7 @@ impl SyntaxContext {
900911
HygieneData::with(|data| data.normalize_to_macro_rules(self))
901912
}
902913

914+
/// See [`SyntaxContextData::outer_expn`]
903915
#[inline]
904916
pub fn outer_expn(self) -> ExpnId {
905917
HygieneData::with(|data| data.outer_expn(self))
@@ -912,6 +924,7 @@ impl SyntaxContext {
912924
HygieneData::with(|data| data.expn_data(data.outer_expn(self)).clone())
913925
}
914926

927+
/// See [`HygieneData::outer_mark`]
915928
#[inline]
916929
fn outer_mark(self) -> (ExpnId, Transparency) {
917930
HygieneData::with(|data| data.outer_mark(self))
@@ -986,15 +999,17 @@ pub struct ExpnData {
986999
pub kind: ExpnKind,
9871000
/// The expansion that produced this expansion.
9881001
pub parent: ExpnId,
989-
/// The location of the actual macro invocation or syntax sugar , e.g.
990-
/// `let x = foo!();` or `if let Some(y) = x {}`
1002+
/// The span of the macro call which produced this expansion.
1003+
///
1004+
/// This span will typically have a different `ExpnData` and `call_site`.
1005+
/// This recursively traces back through any macro calls which expanded into further
1006+
/// macro calls, until the "source call-site" is reached at the root SyntaxContext.
1007+
/// For example, if `food!()` expands to `fruit!()` which then expands to `grape`,
1008+
/// then the call-site of `grape` is `fruit!()` and the call-site of `fruit!()`
1009+
/// is `food!()`.
9911010
///
992-
/// This may recursively refer to other macro invocations, e.g., if
993-
/// `foo!()` invoked `bar!()` internally, and there was an
994-
/// expression inside `bar!`; the call_site of the expression in
995-
/// the expansion would point to the `bar!` invocation; that
996-
/// call_site span would have its own ExpnData, with the call_site
997-
/// pointing to the `foo!` invocation.
1011+
/// For a desugaring expansion, this is the span of the expression or node that was
1012+
/// desugared.
9981013
pub call_site: Span,
9991014
/// Used to force two `ExpnData`s to have different `Fingerprint`s.
10001015
/// Due to macro expansion, it's possible to end up with two `ExpnId`s

‎compiler/rustc_span/src/lib.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -710,8 +710,8 @@ impl Span {
710710
if !ctxt.is_root() { ctxt.outer_expn_data().call_site.source_callsite() } else { self }
711711
}
712712

713-
/// The `Span` for the tokens in the previous macro expansion from which `self` was generated,
714-
/// if any.
713+
/// Returns the call-site span of the last macro expansion which produced this `Span`.
714+
/// (see [`ExpnData::call_site`]). Returns `None` if this is not an expansion.
715715
pub fn parent_callsite(self) -> Option<Span> {
716716
let ctxt = self.ctxt();
717717
(!ctxt.is_root()).then(|| ctxt.outer_expn_data().call_site)

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /