bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

expand unused doc comment diagnostic

Browse source 
Report the diagnostic on macro expansions, and add a label indicating
why the comment is unused.
This commit is contained in:
Andy Russell 2019-01-24 15:49:03 -05:00
parent 018d4d265f
commit daf80f721b
No known key found for this signature in database
GPG key ID: BE2221033EDBC374
14 changed files with 303 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

2
src/libcore/num/mod.rs
View file

@ -4515,7 +4515,7 @@ macro_rules! rev {
)*}
}
/// intra-sign conversions
// intra-sign conversions
try_from_upper_bounded!(u16, u8);
try_from_upper_bounded!(u32, u16, u8);
try_from_upper_bounded!(u64, u32, u16, u8);

2
src/librustc/hir/mod.rs
View file

@ -122,6 +122,7 @@ impl fmt::Display for HirId {
// hack to ensure that we don't try to access the private parts of `ItemLocalId` in this module
mod item_local_id_inner {
use rustc_data_structures::indexed_vec::Idx;
newtype_index! {
/// An `ItemLocalId` uniquely identifies something within a given "item-like",
/// that is within a hir::Item, hir::TraitItem, or hir::ImplItem. There is no
/// guarantee that the numerical value of a given `ItemLocalId` corresponds to
@ -130,7 +131,6 @@ mod item_local_id_inner {
/// integers starting at zero, so a mapping that maps all or most nodes within
/// an "item-like" to something else can be implement by a `Vec` instead of a
/// tree or hash map.
newtype_index! {
pub struct ItemLocalId { .. }
}
}

3
src/librustc/middle/region.rs
View file

@ -132,6 +132,7 @@ pub enum ScopeData {
Remainder(FirstStatementIndex)
}
newtype_index! {
/// Represents a subscope of `block` for a binding that is introduced
/// by `block.stmts[first_statement_index]`. Such subscopes represent
/// a suffix of the block. Note that each subscope does not include
@ -149,8 +150,6 @@ pub enum ScopeData {
///
/// * The subscope with `first_statement_index == 1` is scope of `c`,
/// and thus does not include EXPR_2, but covers the `...`.
newtype_index! {
pub struct FirstStatementIndex { .. }
}

13
src/librustc/ty/context.rs
View file

@ -1892,9 +1892,11 @@ pub mod tls {
rayon_core::tlv::get()
}
/// A thread local variable which stores a pointer to the current ImplicitCtxt
#[cfg(not(parallel_compiler))]
thread_local!(static TLV: Cell<usize> = Cell::new(0));
thread_local! {
/// A thread local variable which stores a pointer to the current ImplicitCtxt.
static TLV: Cell<usize> = Cell::new(0);
}
/// Sets TLV to `value` during the call to `f`.
/// It is restored to its previous value after.
@ -2011,10 +2013,11 @@ pub mod tls {
})
}
scoped_thread_local! {
/// Stores a pointer to the GlobalCtxt if one is available.
/// This is used to access the GlobalCtxt in the deadlock handler
/// given to Rayon.
scoped_thread_local!(pub static GCX_PTR: Lock<usize>);
/// This is used to access the GlobalCtxt in the deadlock handler given to Rayon.
pub static GCX_PTR: Lock<usize>
}
/// Creates a TyCtxt and ImplicitCtxt based on the GCX_PTR thread local.
/// This is used in the deadlock handler.

2
src/librustc/ty/mod.rs
View file

@ -1512,6 +1512,7 @@ impl<'tcx> InstantiatedPredicates<'tcx> {
}
}
newtype_index! {
/// "Universes" are used during type- and trait-checking in the
/// presence of `for<..>` binders to control what sets of names are
/// visible. Universes are arranged into a tree: the root universe
@ -1547,7 +1548,6 @@ impl<'tcx> InstantiatedPredicates<'tcx> {
/// declared, but a type name in a non-zero universe is a placeholder
/// type -- an idealized representative of "types in general" that we
/// use for checking generic functions.
newtype_index! {
pub struct UniverseIndex {
DEBUG_FORMAT = "U{}",
}

2
src/librustc/ty/sty.rs
View file

@ -1082,6 +1082,7 @@ impl<'a, 'gcx, 'tcx> ParamConst {
}
}
newtype_index! {
/// A [De Bruijn index][dbi] is a standard means of representing
/// regions (and perhaps later types) in a higher-ranked setting. In
/// particular, imagine a type like this:
@ -1121,7 +1122,6 @@ impl<'a, 'gcx, 'tcx> ParamConst {
/// is the outer fn.
///
/// [dbi]: http://en.wikipedia.org/wiki/De_Bruijn_index
newtype_index! {
pub struct DebruijnIndex {
DEBUG_FORMAT = "DebruijnIndex({})",
const INNERMOST = 0,

30
src/librustc_data_structures/indexed_vec.rs
View file

@ -58,9 +58,10 @@ macro_rules! newtype_index {
// ---- public rules ----
// Use default constants
($v:vis struct $name:ident { .. }) => (
($(#[$attrs:meta])* $v:vis struct $name:ident { .. }) => (
newtype_index!(
// Leave out derives marker so we can use its absence to ensure it comes first
@attrs [$(#[$attrs])*]
@type [$name]
// shave off 256 indices at the end to allow space for packing these indices into enums
@max [0xFFFF_FF00]
@ -69,9 +70,10 @@ macro_rules! newtype_index {
);
// Define any constants
($v:vis struct $name:ident { $($tokens:tt)+ }) => (
($(#[$attrs:meta])* $v:vis struct $name:ident { $($tokens:tt)+ }) => (
newtype_index!(
// Leave out derives marker so we can use its absence to ensure it comes first
@attrs [$(#[$attrs])*]
@type [$name]
// shave off 256 indices at the end to allow space for packing these indices into enums
@max [0xFFFF_FF00]
@ -84,10 +86,12 @@ macro_rules! newtype_index {
// Base case, user-defined constants (if any) have already been defined
(@derives [$($derives:ident,)*]
@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$max:expr]
@vis [$v:vis]
@debug_format [$debug_format:tt]) => (
$(#[$attrs])*
#[derive(Copy, PartialEq, Eq, Hash, PartialOrd, Ord, $($derives),*)]
#[rustc_layout_scalar_valid_range_end($max)]
$v struct $type {
@ -317,7 +321,8 @@ macro_rules! newtype_index {
// By not including the @derives marker in this list nor in the default args, we can force it
// to come first if it exists. When encodable isn't custom, add serialization traits by default.
(@type [$type:ident]
(@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$max:expr]
@vis [$v:vis]
@debug_format [$debug_format:tt]
@ -325,6 +330,7 @@ macro_rules! newtype_index {
$($tokens:tt)*) => (
newtype_index!(
@derives [$($derives,)+ RustcEncodable,]
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]
@ -335,7 +341,8 @@ macro_rules! newtype_index {
// The case where no derives are added, but encodable is overridden. Don't
// derive serialization traits
(@type [$type:ident]
(@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$max:expr]
@vis [$v:vis]
@debug_format [$debug_format:tt]
@ -343,6 +350,7 @@ macro_rules! newtype_index {
$($tokens:tt)*) => (
newtype_index!(
@derives []
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]
@ -351,13 +359,15 @@ macro_rules! newtype_index {
);
// The case where no derives are added, add serialization derives by default
(@type [$type:ident]
(@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$max:expr]
@vis [$v:vis]
@debug_format [$debug_format:tt]
$($tokens:tt)*) => (
newtype_index!(
@derives [RustcEncodable,]
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]
@ -384,6 +394,7 @@ macro_rules! newtype_index {
// Rewrite final without comma to one that includes comma
(@derives [$($derives:ident,)*]
@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$max:expr]
@vis [$v:vis]
@ -391,6 +402,7 @@ macro_rules! newtype_index {
$name:ident = $constant:expr) => (
newtype_index!(
@derives [$($derives,)*]
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]
@ -400,6 +412,7 @@ macro_rules! newtype_index {
// Rewrite final const without comma to one that includes comma
(@derives [$($derives:ident,)*]
@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$_max:expr]
@vis [$v:vis]
@ -408,6 +421,7 @@ macro_rules! newtype_index {
const $name:ident = $constant:expr) => (
newtype_index!(
@derives [$($derives,)*]
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]
@ -417,6 +431,7 @@ macro_rules! newtype_index {
// Replace existing default for max
(@derives [$($derives:ident,)*]
@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$_max:expr]
@vis [$v:vis]
@ -425,6 +440,7 @@ macro_rules! newtype_index {
$($tokens:tt)*) => (
newtype_index!(
@derives [$($derives,)*]
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]
@ -434,6 +450,7 @@ macro_rules! newtype_index {
// Replace existing default for debug_format
(@derives [$($derives:ident,)*]
@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$max:expr]
@vis [$v:vis]
@ -442,6 +459,7 @@ macro_rules! newtype_index {
$($tokens:tt)*) => (
newtype_index!(
@derives [$($derives,)*]
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]
@ -451,6 +469,7 @@ macro_rules! newtype_index {
// Assign a user-defined constant
(@derives [$($derives:ident,)*]
@attrs [$(#[$attrs:meta])*]
@type [$type:ident]
@max [$max:expr]
@vis [$v:vis]
@ -462,6 +481,7 @@ macro_rules! newtype_index {
pub const $name: $type = $type::from_u32_const($constant);
newtype_index!(
@derives [$($derives,)*]
@attrs [$(#[$attrs])*]
@type [$type]
@max [$max]
@vis [$v]

53
src/librustc_lint/builtin.rs
View file

@ -36,7 +36,7 @@ use syntax::tokenstream::{TokenTree, TokenStream};
use syntax::ast;
use syntax::ptr::P;
use syntax::ast::Expr;
use syntax::attr;
use syntax::attr::{self, HasAttrs};
use syntax::source_map::Spanned;
use syntax::edition::Edition;
use syntax::feature_gate::{AttributeGate, AttributeTemplate, AttributeType};
@ -802,7 +802,14 @@ impl LintPass for UnusedDocComment {
}
impl UnusedDocComment {
fn warn_if_doc(&self, cx: &EarlyContext, attrs: &[ast::Attribute]) {
fn warn_if_doc(
&self,
cx: &EarlyContext<'_>,
node_span: Span,
node_kind: &str,
is_macro_expansion: bool,
attrs: &[ast::Attribute]
) {
let mut attrs = attrs.into_iter().peekable();
// Accumulate a single span for sugared doc comments.
@ -825,27 +832,51 @@ impl UnusedDocComment {
let span = sugared_span.take().unwrap_or_else(|| attr.span);
if attr.name() == "doc" {
cx.struct_span_lint(
UNUSED_DOC_COMMENTS,
span,
"doc comment not used by rustdoc",
).emit();
let mut err = cx.struct_span_lint(UNUSED_DOC_COMMENTS, span, "unused doc comment");
err.span_label(
node_span,
format!("rustdoc does not generate documentation for {}", node_kind)
);
if is_macro_expansion {
err.help("to document an item produced by a macro, \
the macro must produce the documentation as part of its expansion");
}
err.emit();
}
}
}
}
impl EarlyLintPass for UnusedDocComment {
fn check_local(&mut self, cx: &EarlyContext<'_>, decl: &ast::Local) {
self.warn_if_doc(cx, &decl.attrs);
fn check_item(&mut self, cx: &EarlyContext<'_>, item: &ast::Item) {
if let ast::ItemKind::Mac(..) = item.node {
self.warn_if_doc(cx, item.span, "macro expansions", true, &item.attrs);
}
}
fn check_stmt(&mut self, cx: &EarlyContext<'_>, stmt: &ast::Stmt) {
let (kind, is_macro_expansion) = match stmt.node {
ast::StmtKind::Local(..) => ("statements", false),
ast::StmtKind::Item(..) => ("inner items", false),
ast::StmtKind::Mac(..) => ("macro expansions", true),
// expressions will be reported by `check_expr`.
ast::StmtKind::Semi(..) |
ast::StmtKind::Expr(..) => return,
};
self.warn_if_doc(cx, stmt.span, kind, is_macro_expansion, stmt.node.attrs());
}
fn check_arm(&mut self, cx: &EarlyContext<'_>, arm: &ast::Arm) {
self.warn_if_doc(cx, &arm.attrs);
let arm_span = arm.pats[0].span.with_hi(arm.body.span.hi());
self.warn_if_doc(cx, arm_span, "match arms", false, &arm.attrs);
}
fn check_expr(&mut self, cx: &EarlyContext<'_>, expr: &ast::Expr) {
self.warn_if_doc(cx, &expr.attrs);
self.warn_if_doc(cx, expr.span, "expressions", false, &expr.attrs);
}
}

2
src/librustc_lint/lib.rs
View file

@ -66,6 +66,7 @@ macro_rules! pre_expansion_lint_passes {
($macro:path, $args:tt) => (
$macro!($args, [
KeywordIdents: KeywordIdents,
UnusedDocComment: UnusedDocComment,
]);
)
}
@ -77,7 +78,6 @@ macro_rules! early_lint_passes {
UnusedImportBraces: UnusedImportBraces,
UnsafeCode: UnsafeCode,
AnonymousParameters: AnonymousParameters,
UnusedDocComment: UnusedDocComment,
EllipsisInclusiveRangePatterns: EllipsisInclusiveRangePatterns,
NonCamelCaseTypes: NonCamelCaseTypes,
DeprecatedAttr: DeprecatedAttr::new(),

4
src/librustc_mir/borrow_check/nll/region_infer/values.rs
View file

@ -116,14 +116,14 @@ impl RegionValueElements {
}
}
newtype_index! {
/// A single integer representing a `Location` in the MIR control-flow
/// graph. Constructed efficiently from `RegionValueElements`.
newtype_index! {
pub struct PointIndex { DEBUG_FORMAT = "PointIndex({})" }
}
/// A single integer representing a `ty::Placeholder`.
newtype_index! {
/// A single integer representing a `ty::Placeholder`.
pub struct PlaceholderIndex { DEBUG_FORMAT = "PlaceholderIndex({})" }
}

22
src/librustc_mir/dataflow/move_paths/mod.rs
View file

@ -23,7 +23,7 @@ pub(crate) mod indexes {
use rustc_data_structures::indexed_vec::Idx;
macro_rules! new_index {
($Index:ident, $debug_name:expr) => {
($(#[$attrs:meta])* $Index:ident, $debug_name:expr) => {
#[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct $Index(NonZeroUsize);
@ -44,17 +44,29 @@ pub(crate) mod indexes {
}
}
new_index!(
/// Index into MovePathData.move_paths
new_index!(MovePathIndex, "mp");
MovePathIndex,
"mp"
);
new_index!(
/// Index into MoveData.moves.
new_index!(MoveOutIndex, "mo");
MoveOutIndex,
"mo"
);
new_index!(
/// Index into MoveData.inits.
new_index!(InitIndex, "in");
InitIndex,
"in"
);
new_index!(
/// Index into Borrows.locations
new_index!(BorrowIndex, "bw");
BorrowIndex,
"bw"
);
}
pub use self::indexes::MovePathIndex;

4
src/libstd/io/stdio.rs
View file

@ -11,15 +11,15 @@ use crate::sys::stdio;
use crate::sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard};
use crate::thread::LocalKey;
/// Stdout used by print! and println! macros
thread_local! {
/// Stdout used by print! and println! macros
static LOCAL_STDOUT: RefCell<Option<Box<dyn Write + Send>>> = {
RefCell::new(None)
}
}
/// Stderr used by eprint! and eprintln! macros, and panics
thread_local! {
/// Stderr used by eprint! and eprintln! macros, and panics
static LOCAL_STDERR: RefCell<Option<Box<dyn Write + Send>>> = {
RefCell::new(None)
}

31
src/test/ui/useless_comment.rs
View file

@ -1,24 +1,43 @@
#![feature(stmt_expr_attributes)]
#![deny(unused_doc_comments)]
macro_rules! mac {
() => {}
}
/// foo //~ ERROR unused doc comment
mac!();
fn foo() {
/// a //~ ERROR doc comment not used by rustdoc
/// a //~ ERROR unused doc comment
let x = 12;
/// multi-line //~ doc comment not used by rustdoc
/// multi-line //~ unused doc comment
/// doc comment
/// that is unused
match x {
/// c //~ ERROR doc comment not used by rustdoc
/// c //~ ERROR unused doc comment
1 => {},
_ => {}
}
/// foo //~ ERROR doc comment not used by rustdoc
/// foo //~ ERROR unused doc comment
unsafe {}
#[doc = "foo"] //~ ERROR doc comment not used by rustdoc
#[doc = "bar"] //~ ERROR doc comment not used by rustdoc
#[doc = "foo"] //~ ERROR unused doc comment
#[doc = "bar"] //~ ERROR unused doc comment
3;
/// bar //~ ERROR unused doc comment
mac!();
let x = /** comment */ 47; //~ ERROR unused doc comment
/// dox //~ ERROR unused doc comment
{
}
}
fn main() {

98
src/test/ui/useless_comment.stderr
View file

@ -1,46 +1,98 @@
error: doc comment not used by rustdoc
--> $DIR/useless_comment.rs:4:5
error: unused doc comment
--> $DIR/useless_comment.rs:9:1
|
LL | /// a //~ ERROR doc comment not used by rustdoc
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | /// foo //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | mac!();
| ------- rustdoc does not generate documentation for macro expansions
|
note: lint level defined here
--> $DIR/useless_comment.rs:1:9
--> $DIR/useless_comment.rs:3:9
|
LL | #![deny(unused_doc_comments)]
| ^^^^^^^^^^^^^^^^^^^
= help: to document an item produced by a macro, the macro must produce the documentation as part of its expansion
error: doc comment not used by rustdoc
--> $DIR/useless_comment.rs:7:5
error: unused doc comment
--> $DIR/useless_comment.rs:13:5
|
LL | / /// multi-line //~ doc comment not used by rustdoc
LL | /// a //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | let x = 12;
| ----------- rustdoc does not generate documentation for statements
error: unused doc comment
--> $DIR/useless_comment.rs:16:5
|
LL | / /// multi-line //~ unused doc comment
LL | | /// doc comment
LL | | /// that is unused
| |______________________^
LL | / match x {
LL | | /// c //~ ERROR unused doc comment
LL | | 1 => {},
LL | | _ => {}
LL | | }
| |_____- rustdoc does not generate documentation for expressions
error: doc comment not used by rustdoc
--> $DIR/useless_comment.rs:11:9
error: unused doc comment
--> $DIR/useless_comment.rs:20:9
|
LL | /// c //~ ERROR doc comment not used by rustdoc
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | /// c //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | 1 => {},
| ------- rustdoc does not generate documentation for match arms
error: doc comment not used by rustdoc
--> $DIR/useless_comment.rs:16:5
error: unused doc comment
--> $DIR/useless_comment.rs:25:5
|
LL | /// foo //~ ERROR doc comment not used by rustdoc
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | /// foo //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | unsafe {}
| --------- rustdoc does not generate documentation for expressions
error: doc comment not used by rustdoc
--> $DIR/useless_comment.rs:19:5
error: unused doc comment
--> $DIR/useless_comment.rs:28:5
|
LL | #[doc = "foo"] //~ ERROR doc comment not used by rustdoc
LL | #[doc = "foo"] //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^
LL | #[doc = "bar"] //~ ERROR unused doc comment
LL | 3;
| - rustdoc does not generate documentation for expressions
error: doc comment not used by rustdoc
--> $DIR/useless_comment.rs:20:5
error: unused doc comment
--> $DIR/useless_comment.rs:29:5
|
LL | #[doc = "bar"] //~ ERROR doc comment not used by rustdoc
LL | #[doc = "bar"] //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^
LL | 3;
| - rustdoc does not generate documentation for expressions
error: aborting due to 6 previous errors
error: unused doc comment
--> $DIR/useless_comment.rs:32:5
|
LL | /// bar //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | mac!();
| ------- rustdoc does not generate documentation for macro expansions
|
= help: to document an item produced by a macro, the macro must produce the documentation as part of its expansion
error: unused doc comment
--> $DIR/useless_comment.rs:35:13
|
LL | let x = /** comment */ 47; //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^ -- rustdoc does not generate documentation for expressions
error: unused doc comment
--> $DIR/useless_comment.rs:37:5
|
LL | /// dox //~ ERROR unused doc comment
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | / {
LL | |
LL | | }
| |_____- rustdoc does not generate documentation for expressions
error: aborting due to 10 previous errors