Auto merge of #82994 - camelid:rename-source-to-span, r=jyn514

Rename `source` to `span` and `span` to `source`

- Rename `clean::Item.source` to `span`
- Rename `clean::Span::span()` to `clean::Span::inner()`
- Rename `rustdoc_json_types::Item.source` to `span`
- rustdoc-json: Rename `Import.span` to `Import.source`

*See also the [discussion on Zulip][z] (this is a bit more than discussed in
that conversation, but all the changes are related).*

r? `@jyn514`

[z]: https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/get.20span.20of.20file.20from.20name/near/229603729

src/librustdoc/clean/auto_trait.rs

@@ -110,7 +110,7 @@ impl<'a, 'tcx> AutoTraitFinder<'a, 'tcx> {
         };
 
         Some(Item {
-            source: Span::dummy(),
+            span: Span::dummy(),
             name: None,
             attrs: Default::default(),
             visibility: Inherited,

src/librustdoc/clean/blanket_impl.rs

@@ -102,7 +102,7 @@ impl<'a, 'tcx> BlanketImplFinder<'a, 'tcx> {
                     .collect();
 
                 impls.push(Item {
-                    source: self.cx.tcx.def_span(impl_def_id).clean(self.cx),
+                    span: self.cx.tcx.def_span(impl_def_id).clean(self.cx),
                     name: None,
                     attrs: Default::default(),
                     visibility: Inherited,

src/librustdoc/clean/inline.rs

@@ -459,7 +459,7 @@ fn build_module(
                 items.push(clean::Item {
                     name: None,
                     attrs: box clean::Attributes::default(),
-                    source: clean::Span::dummy(),
+                    span: clean::Span::dummy(),
                     def_id: DefId::local(CRATE_DEF_INDEX),
                     visibility: clean::Public,
                     kind: box clean::ImportItem(clean::Import::new_simple(

src/librustdoc/clean/mod.rs

@@ -235,7 +235,7 @@ impl Clean<Item> for doctree::Module<'_> {
             ModuleItem(Module { is_crate: self.is_crate, items }),
             cx,
         );
-        Item { source: span.clean(cx), ..what_rustc_thinks }
+        Item { span: span.clean(cx), ..what_rustc_thinks }
     }
 }
 
@@ -2132,7 +2132,7 @@ fn clean_extern_crate(
     vec![Item {
         name: Some(name),
         attrs: box attrs.clean(cx),
-        source: krate.span.clean(cx),
+        span: krate.span.clean(cx),
         def_id: crate_def_id,
         visibility: krate.vis.clean(cx),
         kind: box ExternCrateItem { src: orig_name },

src/librustdoc/clean/types.rs

@@ -81,12 +81,14 @@ crate struct ExternalCrate {
 /// directly to the AST's concept of an item; it's a strict superset.
 #[derive(Clone)]
 crate struct Item {
-    /// Stringified span
-    crate source: Span,
-    /// Not everything has a name. E.g., impls
+    crate span: Span,
+    /// The name of this item.
+    /// Optional because not every item has a name, e.g. impls.
     crate name: Option<Symbol>,
     crate attrs: Box<Attributes>,
     crate visibility: Visibility,
+    /// Information about this item that is specific to what kind of item it is.
+    /// E.g., struct vs enum vs function.
     crate kind: Box<ItemKind>,
     crate def_id: DefId,
 }
@@ -100,7 +102,7 @@ impl fmt::Debug for Item {
         let def_id: &dyn fmt::Debug = if self.is_fake() { &"**FAKE**" } else { &self.def_id };
 
         fmt.debug_struct("Item")
-            .field("source", &self.source)
+            .field("source", &self.span)
             .field("name", &self.name)
             .field("attrs", &self.attrs)
             .field("kind", &self.kind)
@@ -165,7 +167,7 @@ impl Item {
         debug!("name={:?}, def_id={:?}", name, def_id);
 
         // `span_if_local()` lies about functions and only gives the span of the function signature
-        let source = def_id.as_local().map_or_else(
+        let span = def_id.as_local().map_or_else(
             || cx.tcx.def_span(def_id),
             |local| {
                 let hir = cx.tcx.hir();
@@ -177,7 +179,7 @@ impl Item {
             def_id,
             kind: box kind,
             name,
-            source: source.clean(cx),
+            span: span.clean(cx),
             attrs,
             visibility: cx.tcx.visibility(def_id).clean(cx),
         }
@@ -559,6 +561,8 @@ impl<'a> FromIterator<&'a DocFragment> for String {
     }
 }
 
+/// The attributes on an [`Item`], including attributes like `#[derive(...)]` and `#[inline]`,
+/// as well as doc comments.
 #[derive(Clone, Debug, Default)]
 crate struct Attributes {
     crate doc_strings: Vec<DocFragment>,
@@ -1798,8 +1802,13 @@ impl From<hir::PrimTy> for PrimitiveType {
 
 #[derive(Copy, Clone, Debug)]
 crate enum Visibility {
+    /// `pub`
     Public,
+    /// Visibility inherited from parent.
+    ///
+    /// For example, this is the visibility of private items and of enum variants.
     Inherited,
+    /// `pub(crate)`, `pub(super)`, or `pub(in path::to::somewhere)`
     Restricted(DefId),
 }
 
@@ -1848,7 +1857,8 @@ crate enum Variant {
     Struct(VariantStruct),
 }
 
-/// Small wrapper around `rustc_span::Span` that adds helper methods and enforces calling `source_callsite`.
+/// Small wrapper around [`rustc_span::Span]` that adds helper methods
+/// and enforces calling [`rustc_span::Span::source_callsite()`].
 #[derive(Clone, Debug)]
 crate struct Span(rustc_span::Span);
 
@@ -1860,12 +1870,12 @@ impl Span {
         Self(sp.source_callsite())
     }
 
-    crate fn dummy() -> Self {
-        Self(rustc_span::DUMMY_SP)
+    crate fn inner(&self) -> rustc_span::Span {
+        self.0
     }
 
-    crate fn span(&self) -> rustc_span::Span {
-        self.0
+    crate fn dummy() -> Self {
+        Self(rustc_span::DUMMY_SP)
     }
 
     crate fn is_dummy(&self) -> bool {

src/librustdoc/html/render/context.rs

@@ -228,15 +228,15 @@ impl<'tcx> Context<'tcx> {
     /// may happen, for example, with externally inlined items where the source
     /// of their crate documentation isn't known.
     pub(super) fn src_href(&self, item: &clean::Item) -> Option<String> {
-        if item.source.is_dummy() {
+        if item.span.is_dummy() {
             return None;
         }
         let mut root = self.root_path();
         let mut path = String::new();
-        let cnum = item.source.cnum(self.sess());
+        let cnum = item.span.cnum(self.sess());
 
         // We can safely ignore synthetic `SourceFile`s.
-        let file = match item.source.filename(self.sess()) {
+        let file = match item.span.filename(self.sess()) {
             FileName::Real(ref path) => path.local_path().to_path_buf(),
             _ => return None,
         };
@@ -270,8 +270,8 @@ impl<'tcx> Context<'tcx> {
             (&*symbol, &path)
         };
 
-        let loline = item.source.lo(self.sess()).line;
-        let hiline = item.source.hi(self.sess()).line;
+        let loline = item.span.lo(self.sess()).line;
+        let hiline = item.span.hi(self.sess()).line;
         let lines =
             if loline == hiline { loline.to_string() } else { format!("{}-{}", loline, hiline) };
         Some(format!(

src/librustdoc/html/render/print_item.rs

@@ -937,7 +937,7 @@ fn item_macro(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Mac
             Some("macro"),
             None,
             None,
-            it.source.span().edition(),
+            it.span.inner().edition(),
         );
     });
     document(w, cx, it, None)

src/librustdoc/html/sources.rs

@@ -41,11 +41,11 @@ impl DocFolder for SourceCollector<'_, '_> {
         // then we need to render it out to the filesystem.
         if self.scx.include_sources
             // skip all synthetic "files"
-            && item.source.filename(self.sess()).is_real()
+            && item.span.filename(self.sess()).is_real()
             // skip non-local files
-            && item.source.cnum(self.sess()) == LOCAL_CRATE
+            && item.span.cnum(self.sess()) == LOCAL_CRATE
         {
-            let filename = item.source.filename(self.sess());
+            let filename = item.span.filename(self.sess());
             // If it turns out that we couldn't read this file, then we probably
             // can't read any of the files (generating html output from json or
             // something like that), so just don't include sources for the

src/librustdoc/json/conversions.rs

@@ -24,7 +24,7 @@ use std::collections::HashSet;
 impl JsonRenderer<'_> {
     pub(super) fn convert_item(&self, item: clean::Item) -> Option<Item> {
         let deprecation = item.deprecation(self.tcx);
-        let clean::Item { source, name, attrs, kind, visibility, def_id } = item;
+        let clean::Item { span, name, attrs, kind, visibility, def_id } = item;
         let inner = match *kind {
             clean::StrippedItem(_) => return None,
             x => from_clean_item_kind(x, self.tcx, &name),
@@ -33,7 +33,7 @@ impl JsonRenderer<'_> {
             id: from_def_id(def_id),
             crate_id: def_id.krate.as_u32(),
             name: name.map(|sym| sym.to_string()),
-            source: self.convert_span(source),
+            span: self.convert_span(span),
             visibility: self.convert_visibility(visibility),
             docs: attrs.collapsed_doc_value(),
             links: attrs
@@ -503,13 +503,13 @@ impl From<clean::Import> for Import {
         use clean::ImportKind::*;
         match import.kind {
             Simple(s) => Import {
-                span: import.source.path.whole_name(),
+                source: import.source.path.whole_name(),
                 name: s.to_string(),
                 id: import.source.did.map(from_def_id),
                 glob: false,
             },
             Glob => Import {
-                span: import.source.path.whole_name(),
+                source: import.source.path.whole_name(),
                 name: import.source.path.last_name().to_string(),
                 id: import.source.did.map(from_def_id),
                 glob: true,

src/librustdoc/json/mod.rs

@@ -109,7 +109,7 @@ impl JsonRenderer<'tcx> {
                                 .map(Clone::clone),
                             visibility: types::Visibility::Public,
                             inner: types::ItemEnum::Trait(trait_item.clone().into()),
-                            source: None,
+                            span: None,
                             docs: Default::default(),
                             links: Default::default(),
                             attrs: Default::default(),
@@ -246,7 +246,7 @@ impl<'tcx> FormatRenderer<'tcx> for JsonRenderer<'tcx> {
                     )
                 })
                 .collect(),
-            format_version: 4,
+            format_version: 5,
         };
         let mut p = self.out_path.clone();
         p.push(output.index.get(&output.root).unwrap().name.clone().unwrap());

src/librustdoc/passes/calculate_doc_coverage.rs

@@ -212,7 +212,7 @@ impl<'a, 'b> fold::DocFolder for CoverageCalculator<'a, 'b> {
                 return Some(i);
             }
             clean::ImplItem(ref impl_) => {
-                let filename = i.source.filename(self.ctx.sess());
+                let filename = i.span.filename(self.ctx.sess());
                 if let Some(ref tr) = impl_.trait_ {
                     debug!(
                         "impl {:#} for {:#} in {}",
@@ -243,7 +243,7 @@ impl<'a, 'b> fold::DocFolder for CoverageCalculator<'a, 'b> {
                     None,
                 );
 
-                let filename = i.source.filename(self.ctx.sess());
+                let filename = i.span.filename(self.ctx.sess());
                 let has_doc_example = tests.found_tests != 0;
                 let hir_id = self.ctx.tcx.hir().local_def_id_to_hir_id(i.def_id.expect_local());
                 let (level, source) = self.ctx.tcx.lint_level_at_node(MISSING_DOCS, hir_id);

src/librustdoc/passes/check_code_block_syntax.rs

@@ -86,7 +86,7 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> {
                 // We couldn't calculate the span of the markdown block that had the error, so our
                 // diagnostics are going to be a bit lacking.
                 let mut diag = self.cx.sess().struct_span_warn(
-                    super::span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
+                    super::span_of_attrs(&item.attrs).unwrap_or(item.span.inner()),
                     "doc comment contains an invalid Rust code block",
                 );
 
@@ -110,7 +110,7 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> {
 impl<'a, 'tcx> DocFolder for SyntaxChecker<'a, 'tcx> {
     fn fold_item(&mut self, item: clean::Item) -> Option<clean::Item> {
         if let Some(dox) = &item.attrs.collapsed_doc_value() {
-            let sp = span_of_attrs(&item.attrs).unwrap_or(item.source.span());
+            let sp = span_of_attrs(&item.attrs).unwrap_or(item.span.inner());
             let extra = crate::html::markdown::ExtraInfo::new_did(self.cx.tcx, item.def_id, sp);
             for code_block in markdown::rust_code_blocks(&dox, &extra) {
                 self.check_rust_syntax(&item, &dox, code_block);

src/librustdoc/passes/collect_intra_doc_links.rs

@@ -1226,9 +1226,7 @@ impl LinkCollector<'_, '_> {
                             &ori_link.range,
                             &item.attrs,
                         )
-                        .unwrap_or_else(|| {
-                            span_of_attrs(&item.attrs).unwrap_or(item.source.span())
-                        });
+                        .unwrap_or_else(|| span_of_attrs(&item.attrs).unwrap_or(item.span.inner()));
 
                         rustc_session::parse::feature_err(
                             &self.cx.tcx.sess.parse_sess,
@@ -1693,7 +1691,7 @@ fn report_diagnostic(
     };
 
     let attrs = &item.attrs;
-    let sp = span_of_attrs(attrs).unwrap_or(item.source.span());
+    let sp = span_of_attrs(attrs).unwrap_or(item.span.inner());
 
     tcx.struct_span_lint_hir(lint, hir_id, sp, |lint| {
         let mut diag = lint.build(msg);

src/librustdoc/passes/doc_test_lints.rs

@@ -97,7 +97,7 @@ crate fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
     if tests.found_tests == 0 && cx.tcx.sess.is_nightly_build() {
         if should_have_doc_example(cx, &item) {
             debug!("reporting error for {:?} (hir_id={:?})", item, hir_id);
-            let sp = span_of_attrs(&item.attrs).unwrap_or(item.source.span());
+            let sp = span_of_attrs(&item.attrs).unwrap_or(item.span.inner());
             cx.tcx.struct_span_lint_hir(
                 crate::lint::MISSING_DOC_CODE_EXAMPLES,
                 hir_id,
@@ -109,7 +109,7 @@ crate fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
         cx.tcx.struct_span_lint_hir(
             crate::lint::PRIVATE_DOC_TESTS,
             hir_id,
-            span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
+            span_of_attrs(&item.attrs).unwrap_or(item.span.inner()),
             |lint| lint.build("documentation test in private item").emit(),
         );
     }

src/librustdoc/passes/html_tags.rs

@@ -181,7 +181,7 @@ impl<'a, 'tcx> DocFolder for InvalidHtmlTagsLinter<'a, 'tcx> {
                 let sp = match super::source_span_for_markdown_range(tcx, &dox, range, &item.attrs)
                 {
                     Some(sp) => sp,
-                    None => span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
+                    None => span_of_attrs(&item.attrs).unwrap_or(item.span.inner()),
                 };
                 tcx.struct_span_lint_hir(crate::lint::INVALID_HTML_TAGS, hir_id, sp, |lint| {
                     lint.build(msg).emit()

src/librustdoc/passes/non_autolinks.rs

@@ -72,7 +72,7 @@ impl<'a, 'tcx> DocFolder for NonAutolinksLinter<'a, 'tcx> {
             let report_diag = |cx: &DocContext<'_>, msg: &str, url: &str, range: Range<usize>| {
                 let sp = super::source_span_for_markdown_range(cx.tcx, &dox, &range, &item.attrs)
                     .or_else(|| span_of_attrs(&item.attrs))
-                    .unwrap_or(item.source.span());
+                    .unwrap_or(item.span.inner());
                 cx.tcx.struct_span_lint_hir(crate::lint::NON_AUTOLINKS, hir_id, sp, |lint| {
                     lint.build(msg)
                         .span_suggestion(

src/rustdoc-json-types/lib.rs

@@ -64,7 +64,7 @@ pub struct Item {
     pub name: Option<String>,
     /// The source location of this item (absent if it came from a macro expansion or inline
     /// assembly).
-    pub source: Option<Span>,
+    pub span: Option<Span>,
     /// By default all documented items are public, but you can tell rustdoc to output private items
     /// so this field is needed to differentiate.
     pub visibility: Visibility,
@@ -461,7 +461,7 @@ pub struct Impl {
 #[serde(rename_all = "snake_case")]
 pub struct Import {
     /// The full path being imported.
-    pub span: String,
+    pub source: String,
     /// May be different from the last segment of `source` when renaming imports:
     /// `use source as name;`
     pub name: String,

src/test/rustdoc-json/nested.rs

@@ -24,7 +24,7 @@ pub mod l1 {
         // @has - "$.index[*][?(@.name=='l3')].inner.items[*]" $l4_id
         pub struct L4;
     }
-    // @is nested.json "$.index[*][?(@.inner.span=='l3::L4')].kind" \"import\"
-    // @is - "$.index[*][?(@.inner.span=='l3::L4')].inner.glob" false
+    // @is nested.json "$.index[*][?(@.inner.source=='l3::L4')].kind" \"import\"
+    // @is - "$.index[*][?(@.inner.source=='l3::L4')].inner.glob" false
     pub use l3::L4;
 }

src/test/rustdoc-json/reexport/rename_public.rs

@@ -13,5 +13,5 @@ pub mod inner {
 // @set import_id = - "$.index[*][?(@.inner.name=='NewName')].id"
 // @!has - "$.index[*][?(@.inner.name=='Public')]"
 // @has - "$.index[*][?(@.name=='rename_public')].inner.items[*]" $import_id
-// @is - "$.index[*][?(@.inner.name=='NewName')].inner.span" \"inner::Public\"
+// @is - "$.index[*][?(@.inner.name=='NewName')].inner.source" \"inner::Public\"
 pub use inner::Public as NewName;

src/test/rustdoc-json/reexport/simple_public.rs

@@ -14,5 +14,5 @@ pub mod inner {
 
 // @set import_id = - "$.index[*][?(@.inner.name=='Public')].id"
 // @has - "$.index[*][?(@.name=='simple_public')].inner.items[*]" $import_id
-// @is - "$.index[*][?(@.inner.name=='Public')].inner.span" \"inner::Public\"
+// @is - "$.index[*][?(@.inner.name=='Public')].inner.source" \"inner::Public\"
 pub use inner::Public;