Skip to content

Commit e1b8898

Browse files
borsbors
committedMar 9, 2019
Auto merge of #57882 - euclio:unused-doc-attributes, r=estebank
overhaul unused doc comments lint This PR contains a number of improvements to the `unused_doc_comments` lint. - Extends the span to cover the entire comment when using sugared doc comments. - Triggers the lint for all unused doc comments on a node, instead of just the first one. - Triggers the lint on macro expansions, and provides a help note explaining that doc comments must be expanded by the macro. - Adds a label pointing at the node that cannot be documented. Furthermore, this PR fixes any instances in rustc where a macro expansion was erroneously documented.
·
1.85.11.35.0
2 parents c9f8304 + daf80f7 commit e1b8898

File tree

14 files changed

+342
-163
lines changed

14 files changed

+342
-163
lines changed
 

‎src/libcore/num/mod.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -4515,7 +4515,7 @@ macro_rules! rev {
45154515
)*}
45164516
}
45174517

4518-
/// intra-sign conversions
4518+
// intra-sign conversions
45194519
try_from_upper_bounded!(u16, u8);
45204520
try_from_upper_bounded!(u32, u16, u8);
45214521
try_from_upper_bounded!(u64, u32, u16, u8);

‎src/librustc/hir/mod.rs

+8-8
Original file line numberDiff line numberDiff line change
@@ -122,15 +122,15 @@ impl fmt::Display for HirId {
122122
// hack to ensure that we don't try to access the private parts of `ItemLocalId` in this module
123123
mod item_local_id_inner {
124124
use rustc_data_structures::indexed_vec::Idx;
125-
/// An `ItemLocalId` uniquely identifies something within a given "item-like",
126-
/// that is within a hir::Item, hir::TraitItem, or hir::ImplItem. There is no
127-
/// guarantee that the numerical value of a given `ItemLocalId` corresponds to
128-
/// the node's position within the owning item in any way, but there is a
129-
/// guarantee that the `LocalItemId`s within an owner occupy a dense range of
130-
/// integers starting at zero, so a mapping that maps all or most nodes within
131-
/// an "item-like" to something else can be implement by a `Vec` instead of a
132-
/// tree or hash map.
133125
newtype_index! {
126+
/// An `ItemLocalId` uniquely identifies something within a given "item-like",
127+
/// that is within a hir::Item, hir::TraitItem, or hir::ImplItem. There is no
128+
/// guarantee that the numerical value of a given `ItemLocalId` corresponds to
129+
/// the node's position within the owning item in any way, but there is a
130+
/// guarantee that the `LocalItemId`s within an owner occupy a dense range of
131+
/// integers starting at zero, so a mapping that maps all or most nodes within
132+
/// an "item-like" to something else can be implement by a `Vec` instead of a
133+
/// tree or hash map.
134134
pub struct ItemLocalId { .. }
135135
}
136136
}

‎src/librustc/middle/region.rs

+17-18
Original file line numberDiff line numberDiff line change
@@ -132,25 +132,24 @@ pub enum ScopeData {
132132
Remainder(FirstStatementIndex)
133133
}
134134

135-
/// Represents a subscope of `block` for a binding that is introduced
136-
/// by `block.stmts[first_statement_index]`. Such subscopes represent
137-
/// a suffix of the block. Note that each subscope does not include
138-
/// the initializer expression, if any, for the statement indexed by
139-
/// `first_statement_index`.
140-
///
141-
/// For example, given `{ let (a, b) = EXPR_1; let c = EXPR_2; ... }`:
142-
///
143-
/// * The subscope with `first_statement_index == 0` is scope of both
144-
/// `a` and `b`; it does not include EXPR_1, but does include
145-
/// everything after that first `let`. (If you want a scope that
146-
/// includes EXPR_1 as well, then do not use `Scope::Remainder`,
147-
/// but instead another `Scope` that encompasses the whole block,
148-
/// e.g., `Scope::Node`.
149-
///
150-
/// * The subscope with `first_statement_index == 1` is scope of `c`,
151-
/// and thus does not include EXPR_2, but covers the `...`.
152-
153135
newtype_index! {
136+
/// Represents a subscope of `block` for a binding that is introduced
137+
/// by `block.stmts[first_statement_index]`. Such subscopes represent
138+
/// a suffix of the block. Note that each subscope does not include
139+
/// the initializer expression, if any, for the statement indexed by
140+
/// `first_statement_index`.
141+
///
142+
/// For example, given `{ let (a, b) = EXPR_1; let c = EXPR_2; ... }`:
143+
///
144+
/// * The subscope with `first_statement_index == 0` is scope of both
145+
/// `a` and `b`; it does not include EXPR_1, but does include
146+
/// everything after that first `let`. (If you want a scope that
147+
/// includes EXPR_1 as well, then do not use `Scope::Remainder`,
148+
/// but instead another `Scope` that encompasses the whole block,
149+
/// e.g., `Scope::Node`.
150+
///
151+
/// * The subscope with `first_statement_index == 1` is scope of `c`,
152+
/// and thus does not include EXPR_2, but covers the `...`.
154153
pub struct FirstStatementIndex { .. }
155154
}
156155

‎src/librustc/ty/context.rs

+9-6
Original file line numberDiff line numberDiff line change
@@ -1892,9 +1892,11 @@ pub mod tls {
18921892
rayon_core::tlv::get()
18931893
}
18941894

1895-
/// A thread local variable which stores a pointer to the current ImplicitCtxt
18961895
#[cfg(not(parallel_compiler))]
1897-
thread_local!(static TLV: Cell<usize> = Cell::new(0));
1896+
thread_local! {
1897+
/// A thread local variable which stores a pointer to the current ImplicitCtxt.
1898+
static TLV: Cell<usize> = Cell::new(0);
1899+
}
18981900

18991901
/// Sets TLV to `value` during the call to `f`.
19001902
/// It is restored to its previous value after.
@@ -2011,10 +2013,11 @@ pub mod tls {
20112013
})
20122014
}
20132015

2014-
/// Stores a pointer to the GlobalCtxt if one is available.
2015-
/// This is used to access the GlobalCtxt in the deadlock handler
2016-
/// given to Rayon.
2017-
scoped_thread_local!(pub static GCX_PTR: Lock<usize>);
2016+
scoped_thread_local! {
2017+
/// Stores a pointer to the GlobalCtxt if one is available.
2018+
/// This is used to access the GlobalCtxt in the deadlock handler given to Rayon.
2019+
pub static GCX_PTR: Lock<usize>
2020+
}
20182021

20192022
/// Creates a TyCtxt and ImplicitCtxt based on the GCX_PTR thread local.
20202023
/// This is used in the deadlock handler.

‎src/librustc/ty/mod.rs

+35-35
Original file line numberDiff line numberDiff line change
@@ -1512,42 +1512,42 @@ impl<'tcx> InstantiatedPredicates<'tcx> {
15121512
}
15131513
}
15141514

1515-
/// "Universes" are used during type- and trait-checking in the
1516-
/// presence of `for<..>` binders to control what sets of names are
1517-
/// visible. Universes are arranged into a tree: the root universe
1518-
/// contains names that are always visible. Each child then adds a new
1519-
/// set of names that are visible, in addition to those of its parent.
1520-
/// We say that the child universe "extends" the parent universe with
1521-
/// new names.
1522-
///
1523-
/// To make this more concrete, consider this program:
1524-
///
1525-
/// ```
1526-
/// struct Foo { }
1527-
/// fn bar<T>(x: T) {
1528-
/// let y: for<'a> fn(&'a u8, Foo) = ...;
1529-
/// }
1530-
/// ```
1531-
///
1532-
/// The struct name `Foo` is in the root universe U0. But the type
1533-
/// parameter `T`, introduced on `bar`, is in an extended universe U1
1534-
/// -- i.e., within `bar`, we can name both `T` and `Foo`, but outside
1535-
/// of `bar`, we cannot name `T`. Then, within the type of `y`, the
1536-
/// region `'a` is in a universe U2 that extends U1, because we can
1537-
/// name it inside the fn type but not outside.
1538-
///
1539-
/// Universes are used to do type- and trait-checking around these
1540-
/// "forall" binders (also called **universal quantification**). The
1541-
/// idea is that when, in the body of `bar`, we refer to `T` as a
1542-
/// type, we aren't referring to any type in particular, but rather a
1543-
/// kind of "fresh" type that is distinct from all other types we have
1544-
/// actually declared. This is called a **placeholder** type, and we
1545-
/// use universes to talk about this. In other words, a type name in
1546-
/// universe 0 always corresponds to some "ground" type that the user
1547-
/// declared, but a type name in a non-zero universe is a placeholder
1548-
/// type -- an idealized representative of "types in general" that we
1549-
/// use for checking generic functions.
15501515
newtype_index! {
1516+
/// "Universes" are used during type- and trait-checking in the
1517+
/// presence of `for<..>` binders to control what sets of names are
1518+
/// visible. Universes are arranged into a tree: the root universe
1519+
/// contains names that are always visible. Each child then adds a new
1520+
/// set of names that are visible, in addition to those of its parent.
1521+
/// We say that the child universe "extends" the parent universe with
1522+
/// new names.
1523+
///
1524+
/// To make this more concrete, consider this program:
1525+
///
1526+
/// ```
1527+
/// struct Foo { }
1528+
/// fn bar<T>(x: T) {
1529+
/// let y: for<'a> fn(&'a u8, Foo) = ...;
1530+
/// }
1531+
/// ```
1532+
///
1533+
/// The struct name `Foo` is in the root universe U0. But the type
1534+
/// parameter `T`, introduced on `bar`, is in an extended universe U1
1535+
/// -- i.e., within `bar`, we can name both `T` and `Foo`, but outside
1536+
/// of `bar`, we cannot name `T`. Then, within the type of `y`, the
1537+
/// region `'a` is in a universe U2 that extends U1, because we can
1538+
/// name it inside the fn type but not outside.
1539+
///
1540+
/// Universes are used to do type- and trait-checking around these
1541+
/// "forall" binders (also called **universal quantification**). The
1542+
/// idea is that when, in the body of `bar`, we refer to `T` as a
1543+
/// type, we aren't referring to any type in particular, but rather a
1544+
/// kind of "fresh" type that is distinct from all other types we have
1545+
/// actually declared. This is called a **placeholder** type, and we
1546+
/// use universes to talk about this. In other words, a type name in
1547+
/// universe 0 always corresponds to some "ground" type that the user
1548+
/// declared, but a type name in a non-zero universe is a placeholder
1549+
/// type -- an idealized representative of "types in general" that we
1550+
/// use for checking generic functions.
15511551
pub struct UniverseIndex {
15521552
DEBUG_FORMAT = "U{}",
15531553
}

‎src/librustc/ty/sty.rs

+39-39
Original file line numberDiff line numberDiff line change
@@ -1082,46 +1082,46 @@ impl<'a, 'gcx, 'tcx> ParamConst {
10821082
}
10831083
}
10841084

1085-
/// A [De Bruijn index][dbi] is a standard means of representing
1086-
/// regions (and perhaps later types) in a higher-ranked setting. In
1087-
/// particular, imagine a type like this:
1088-
///
1089-
/// for<'a> fn(for<'b> fn(&'b isize, &'a isize), &'a char)
1090-
/// ^ ^ | | |
1091-
/// | | | | |
1092-
/// | +------------+ 0 | |
1093-
/// | | |
1094-
/// +--------------------------------+ 1 |
1095-
/// | |
1096-
/// +------------------------------------------+ 0
1097-
///
1098-
/// In this type, there are two binders (the outer fn and the inner
1099-
/// fn). We need to be able to determine, for any given region, which
1100-
/// fn type it is bound by, the inner or the outer one. There are
1101-
/// various ways you can do this, but a De Bruijn index is one of the
1102-
/// more convenient and has some nice properties. The basic idea is to
1103-
/// count the number of binders, inside out. Some examples should help
1104-
/// clarify what I mean.
1105-
///
1106-
/// Let's start with the reference type `&'b isize` that is the first
1107-
/// argument to the inner function. This region `'b` is assigned a De
1108-
/// Bruijn index of 0, meaning "the innermost binder" (in this case, a
1109-
/// fn). The region `'a` that appears in the second argument type (`&'a
1110-
/// isize`) would then be assigned a De Bruijn index of 1, meaning "the
1111-
/// second-innermost binder". (These indices are written on the arrays
1112-
/// in the diagram).
1113-
///
1114-
/// What is interesting is that De Bruijn index attached to a particular
1115-
/// variable will vary depending on where it appears. For example,
1116-
/// the final type `&'a char` also refers to the region `'a` declared on
1117-
/// the outermost fn. But this time, this reference is not nested within
1118-
/// any other binders (i.e., it is not an argument to the inner fn, but
1119-
/// rather the outer one). Therefore, in this case, it is assigned a
1120-
/// De Bruijn index of 0, because the innermost binder in that location
1121-
/// is the outer fn.
1122-
///
1123-
/// [dbi]: http://en.wikipedia.org/wiki/De_Bruijn_index
11241085
newtype_index! {
1086+
/// A [De Bruijn index][dbi] is a standard means of representing
1087+
/// regions (and perhaps later types) in a higher-ranked setting. In
1088+
/// particular, imagine a type like this:
1089+
///
1090+
/// for<'a> fn(for<'b> fn(&'b isize, &'a isize), &'a char)
1091+
/// ^ ^ | | |
1092+
/// | | | | |
1093+
/// | +------------+ 0 | |
1094+
/// | | |
1095+
/// +--------------------------------+ 1 |
1096+
/// | |
1097+
/// +------------------------------------------+ 0
1098+
///
1099+
/// In this type, there are two binders (the outer fn and the inner
1100+
/// fn). We need to be able to determine, for any given region, which
1101+
/// fn type it is bound by, the inner or the outer one. There are
1102+
/// various ways you can do this, but a De Bruijn index is one of the
1103+
/// more convenient and has some nice properties. The basic idea is to
1104+
/// count the number of binders, inside out. Some examples should help
1105+
/// clarify what I mean.
1106+
///
1107+
/// Let's start with the reference type `&'b isize` that is the first
1108+
/// argument to the inner function. This region `'b` is assigned a De
1109+
/// Bruijn index of 0, meaning "the innermost binder" (in this case, a
1110+
/// fn). The region `'a` that appears in the second argument type (`&'a
1111+
/// isize`) would then be assigned a De Bruijn index of 1, meaning "the
1112+
/// second-innermost binder". (These indices are written on the arrays
1113+
/// in the diagram).
1114+
///
1115+
/// What is interesting is that De Bruijn index attached to a particular
1116+
/// variable will vary depending on where it appears. For example,
1117+
/// the final type `&'a char` also refers to the region `'a` declared on
1118+
/// the outermost fn. But this time, this reference is not nested within
1119+
/// any other binders (i.e., it is not an argument to the inner fn, but
1120+
/// rather the outer one). Therefore, in this case, it is assigned a
1121+
/// De Bruijn index of 0, because the innermost binder in that location
1122+
/// is the outer fn.
1123+
///
1124+
/// [dbi]: http://en.wikipedia.org/wiki/De_Bruijn_index
11251125
pub struct DebruijnIndex {
11261126
DEBUG_FORMAT = "DebruijnIndex({})",
11271127
const INNERMOST = 0,

0 commit comments

Comments
 (0)
Please sign in to comment.