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 31b3915

Browse files
Some hygiene doc improvements
1 parent 154037f commit 31b3915

File tree

2 files changed

+22
-12
lines changed

2 files changed

+22
-12
lines changed

‎compiler/rustc_span/src/hygiene.rs

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ 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+
/// See <https://rustc-dev-guide.rust-lang.org/macro-expansion.html> for more explanation.
4951
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
5052
pub struct SyntaxContext(u32);
5153

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

6264
#[derive(Clone, Copy, Debug)]
6365
struct SyntaxContextData {
66+
/// The last macro expansion in the chain.
67+
/// (Here we say the most deeply nested macro expansion is the "outermost" expansion.)
6468
outer_expn: ExpnId,
69+
/// Transparency of the last macro expansion
6570
outer_transparency: Transparency,
6671
parent: SyntaxContext,
6772
/// This context, but with all transparent and semi-opaque expansions filtered away.
@@ -450,11 +455,13 @@ impl HygieneData {
450455
self.syntax_context_data[ctxt.0 as usize].opaque_and_semiopaque
451456
}
452457

458+
/// See [`SyntaxContextData::outer_expn`]
453459
#[inline]
454460
fn outer_expn(&self, ctxt: SyntaxContext) -> ExpnId {
455461
self.syntax_context_data[ctxt.0 as usize].outer_expn
456462
}
457463

464+
/// The last macro expansion and its Transparency
458465
#[inline]
459466
fn outer_mark(&self, ctxt: SyntaxContext) -> (ExpnId, Transparency) {
460467
let data = &self.syntax_context_data[ctxt.0 as usize];
@@ -900,6 +907,7 @@ impl SyntaxContext {
900907
HygieneData::with(|data| data.normalize_to_macro_rules(self))
901908
}
902909

910+
/// See [`SyntaxContextData::outer_expn`]
903911
#[inline]
904912
pub fn outer_expn(self) -> ExpnId {
905913
HygieneData::with(|data| data.outer_expn(self))
@@ -912,6 +920,7 @@ impl SyntaxContext {
912920
HygieneData::with(|data| data.expn_data(data.outer_expn(self)).clone())
913921
}
914922

923+
/// See [`HygieneData::outer_mark`]
915924
#[inline]
916925
fn outer_mark(self) -> (ExpnId, Transparency) {
917926
HygieneData::with(|data| data.outer_mark(self))
@@ -982,19 +991,20 @@ impl Span {
982991
#[derive(Clone, Debug, Encodable, Decodable, HashStable_Generic)]
983992
pub struct ExpnData {
984993
// --- The part unique to each expansion.
985-
/// The kind of this expansion - macro or compiler desugaring.
986994
pub kind: ExpnKind,
987-
/// The expansion that produced this expansion.
995+
/// The expansion that contains the definition of the macro for this expansion.
988996
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 {}`
997+
/// The span of the macro call which produced this expansion.
998+
///
999+
/// This span will typically have a different `ExpnData` and `call_site`.
1000+
/// This recursively traces back through any macro calls which expanded into further
1001+
/// macro calls, until the "source call-site" is reached at the root SyntaxContext.
1002+
/// For example, if `food!()` expands to `fruit!()` which then expands to `grape`,
1003+
/// then the call-site of `grape` is `fruit!()` and the call-site of `fruit!()`
1004+
/// is `food!()`.
9911005
///
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.
1006+
/// For a desugaring expansion, this is the span of the expression or node that was
1007+
/// desugared.
9981008
pub call_site: Span,
9991009
/// Used to force two `ExpnData`s to have different `Fingerprint`s.
10001010
/// 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 によって変換されたページ (->オリジナル) /