Auto merge of rust-lang#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

Author: bors

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());