From 1d42936b18d08ba414d9def35508d3baf2175c72 Mon Sep 17 00:00:00 2001 From: Maybe Waffle Date: Sun, 27 Nov 2022 11:15:06 +0000 Subject: Prefer doc comments over `//`-comments in compiler --- compiler/rustc_span/src/lib.rs | 14 +++++++------- compiler/rustc_span/src/source_map.rs | 22 +++++++++++----------- compiler/rustc_span/src/symbol.rs | 4 ++-- 3 files changed, 20 insertions(+), 20 deletions(-) (limited to 'compiler/rustc_span/src') diff --git a/compiler/rustc_span/src/lib.rs b/compiler/rustc_span/src/lib.rs index 7ccfa600ec3..1065cd384a9 100644 --- a/compiler/rustc_span/src/lib.rs +++ b/compiler/rustc_span/src/lib.rs @@ -78,10 +78,10 @@ use sha2::Sha256; #[cfg(test)] mod tests; -// Per-session global variables: this struct is stored in thread-local storage -// in such a way that it is accessible without any kind of handle to all -// threads within the compilation session, but is not accessible outside the -// session. +/// Per-session global variables: this struct is stored in thread-local storage +/// in such a way that it is accessible without any kind of handle to all +/// threads within the compilation session, but is not accessible outside the +/// session. pub struct SessionGlobals { symbol_interner: symbol::Interner, span_interner: Lock, @@ -359,8 +359,8 @@ impl FileName { FileNameDisplay { inner: self, display_pref: FileNameDisplayPreference::Remapped } } - // This may include transient local filesystem information. - // Must not be embedded in build outputs. + /// This may include transient local filesystem information. + /// Must not be embedded in build outputs. pub fn prefer_local(&self) -> FileNameDisplay<'_> { FileNameDisplay { inner: self, display_pref: FileNameDisplayPreference::Local } } @@ -751,7 +751,7 @@ impl Span { /// Checks if a span is "internal" to a macro in which `unsafe` /// can be used without triggering the `unsafe_code` lint. - // (that is, a macro marked with `#[allow_internal_unsafe]`). + /// (that is, a macro marked with `#[allow_internal_unsafe]`). pub fn allows_unsafe(self) -> bool { self.ctxt().outer_expn_data().allow_internal_unsafe } diff --git a/compiler/rustc_span/src/source_map.rs b/compiler/rustc_span/src/source_map.rs index e8d129d733c..2ae57d9e56d 100644 --- a/compiler/rustc_span/src/source_map.rs +++ b/compiler/rustc_span/src/source_map.rs @@ -130,14 +130,14 @@ impl FileLoader for RealFileLoader { /// different has no real downsides. #[derive(Copy, Clone, PartialEq, Eq, Hash, Encodable, Decodable, Debug)] pub struct StableSourceFileId { - // A hash of the source file's FileName. This is hash so that it's size - // is more predictable than if we included the actual FileName value. + /// A hash of the source file's [`FileName`]. This is hash so that it's size + /// is more predictable than if we included the actual [`FileName`] value. pub file_name_hash: u64, - // The CrateNum of the crate this source file was originally parsed for. - // We cannot include this information in the hash because at the time - // of hashing we don't have the context to map from the CrateNum's numeric - // value to a StableCrateId. + /// The [`CrateNum`] of the crate this source file was originally parsed for. + /// We cannot include this information in the hash because at the time + /// of hashing we don't have the context to map from the [`CrateNum`]'s numeric + /// value to a `StableCrateId`. pub cnum: CrateNum, } @@ -402,7 +402,7 @@ impl SourceMap { source_file } - // If there is a doctest offset, applies it to the line. + /// If there is a doctest offset, applies it to the line. pub fn doctest_offset_line(&self, file: &FileName, orig: usize) -> usize { match file { FileName::DocTest(_, offset) => { @@ -429,7 +429,7 @@ impl SourceMap { Loc { file: sf, line, col, col_display } } - // If the corresponding `SourceFile` is empty, does not return a line number. + /// If the corresponding `SourceFile` is empty, does not return a line number. pub fn lookup_line(&self, pos: BytePos) -> Result> { let f = self.lookup_source_file(pos); @@ -1053,9 +1053,9 @@ impl SourceMap { SourceFileAndBytePos { sf, pos: offset } } - // Returns the index of the `SourceFile` (in `self.files`) that contains `pos`. - // This index is guaranteed to be valid for the lifetime of this `SourceMap`, - // since `source_files` is a `MonotonicVec` + /// Returns the index of the [`SourceFile`] (in `self.files`) that contains `pos`. + /// This index is guaranteed to be valid for the lifetime of this `SourceMap`, + /// since `source_files` is a `MonotonicVec` pub fn lookup_source_file_idx(&self, pos: BytePos) -> usize { self.files .borrow() diff --git a/compiler/rustc_span/src/symbol.rs b/compiler/rustc_span/src/symbol.rs index aba301dce10..739716cfce3 100644 --- a/compiler/rustc_span/src/symbol.rs +++ b/compiler/rustc_span/src/symbol.rs @@ -2051,8 +2051,8 @@ impl Symbol { } impl Ident { - // Returns `true` for reserved identifiers used internally for elided lifetimes, - // unnamed method parameters, crate root module, error recovery etc. + /// Returns `true` for reserved identifiers used internally for elided lifetimes, + /// unnamed method parameters, crate root module, error recovery etc. pub fn is_special(self) -> bool { self.name.is_special() } -- cgit 1.4.1-3-g733a5