-use clippy_utils::diagnostics::{span_lint, span_lint_and_note};
+use clippy_utils::attrs::is_doc_hidden;
+use clippy_utils::diagnostics::{span_lint, span_lint_and_help, span_lint_and_note};
+use clippy_utils::source::first_line_of_span;
use clippy_utils::ty::{implements_trait, is_type_diagnostic_item};
use clippy_utils::{is_entrypoint_fn, is_expn_of, match_panic_def_id, method_chain_args, return_ty};
use if_chain::if_chain;
use rustc_parse::parser::ForceCollect;
use rustc_session::parse::ParseSess;
use rustc_session::{declare_tool_lint, impl_lint_pass};
+use rustc_span::def_id::LocalDefId;
use rustc_span::edition::Edition;
use rustc_span::source_map::{BytePos, FilePathMapping, MultiSpan, SourceMap, Span};
use rustc_span::{sym, FileName, Pos};
use std::io;
use std::ops::Range;
+use std::thread;
use url::Url;
declare_clippy_lint! {
- /// **What it does:** Checks for the presence of `_`, `::` or camel-case words
+ /// ### What it does
+ /// Checks for the presence of `_`, `::` or camel-case words
/// outside ticks in documentation.
///
- /// **Why is this bad?** *Rustdoc* supports markdown formatting, `_`, `::` and
+ /// ### Why is this bad?
+ /// *Rustdoc* supports markdown formatting, `_`, `::` and
/// camel-case probably indicates some code which should be included between
/// ticks. `_` can also be used for emphasis in markdown, this lint tries to
/// consider that.
///
- /// **Known problems:** Lots of bad docs won’t be fixed, what the lint checks
- /// for is limited, and there are still false positives.
+ /// ### Known problems
+ /// Lots of bad docs won’t be fixed, what the lint checks
+ /// for is limited, and there are still false positives. HTML elements and their
+ /// content are not linted.
///
/// In addition, when writing documentation comments, including `[]` brackets
/// inside a link text would trip the parser. Therfore, documenting link with
/// `[`SmallVec<[T; INLINE_CAPACITY]>`]` and then [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec
/// would fail.
///
- /// **Examples:**
+ /// ### Examples
/// ```rust
/// /// Do something with the foo_bar parameter. See also
/// /// that::other::module::foo.
}
declare_clippy_lint! {
- /// **What it does:** Checks for the doc comments of publicly visible
+ /// ### What it does
+ /// Checks for the doc comments of publicly visible
/// unsafe functions and warns if there is no `# Safety` section.
///
- /// **Why is this bad?** Unsafe functions should document their safety
+ /// ### Why is this bad?
+ /// Unsafe functions should document their safety
/// preconditions, so that users can be sure they are using them safely.
///
- /// **Known problems:** None.
- ///
- /// **Examples:**
+ /// ### Examples
/// ```rust
///# type Universe = ();
/// /// This function should really be documented
}
declare_clippy_lint! {
- /// **What it does:** Checks the doc comments of publicly visible functions that
+ /// ### What it does
+ /// Checks the doc comments of publicly visible functions that
/// return a `Result` type and warns if there is no `# Errors` section.
///
- /// **Why is this bad?** Documenting the type of errors that can be returned from a
+ /// ### Why is this bad?
+ /// Documenting the type of errors that can be returned from a
/// function can help callers write code to handle the errors appropriately.
///
- /// **Known problems:** None.
- ///
- /// **Examples:**
- ///
+ /// ### Examples
/// Since the following function returns a `Result` it has an `# Errors` section in
/// its doc comment:
///
}
declare_clippy_lint! {
- /// **What it does:** Checks the doc comments of publicly visible functions that
+ /// ### What it does
+ /// Checks the doc comments of publicly visible functions that
/// may panic and warns if there is no `# Panics` section.
///
- /// **Why is this bad?** Documenting the scenarios in which panicking occurs
+ /// ### Why is this bad?
+ /// Documenting the scenarios in which panicking occurs
/// can help callers who do not want to panic to avoid those situations.
///
- /// **Known problems:** None.
- ///
- /// **Examples:**
- ///
+ /// ### Examples
/// Since the following function may panic it has a `# Panics` section in
/// its doc comment:
///
}
declare_clippy_lint! {
- /// **What it does:** Checks for `fn main() { .. }` in doctests
+ /// ### What it does
+ /// Checks for `fn main() { .. }` in doctests
///
- /// **Why is this bad?** The test can be shorter (and likely more readable)
+ /// ### Why is this bad?
+ /// The test can be shorter (and likely more readable)
/// if the `fn main()` is left implicit.
///
- /// **Known problems:** None.
- ///
- /// **Examples:**
+ /// ### Examples
/// ``````rust
/// /// An example of a doctest with a `main()` function
/// ///
);
impl<'tcx> LateLintPass<'tcx> for DocMarkdown {
- fn check_crate(&mut self, cx: &LateContext<'tcx>, _: &'tcx hir::Crate<'_>) {
+ fn check_crate(&mut self, cx: &LateContext<'tcx>) {
let attrs = cx.tcx.hir().attrs(hir::CRATE_HIR_ID);
check_attrs(cx, &self.valid_idents, attrs);
}
panic_span: None,
};
fpu.visit_expr(&body.value);
- lint_for_missing_headers(
- cx,
- item.hir_id(),
- item.span,
- sig,
- headers,
- Some(body_id),
- fpu.panic_span,
- );
+ lint_for_missing_headers(cx, item.def_id, item.span, sig, headers, Some(body_id), fpu.panic_span);
}
},
hir::ItemKind::Impl(ref impl_) => {
self.in_trait_impl = impl_.of_trait.is_some();
},
- _ => {},
+ hir::ItemKind::Trait(_, unsafety, ..) => {
+ if !headers.safety && unsafety == hir::Unsafety::Unsafe {
+ span_lint(
+ cx,
+ MISSING_SAFETY_DOC,
+ item.span,
+ "docs for unsafe trait missing `# Safety` section",
+ );
+ }
+ },
+ _ => (),
}
}
let headers = check_attrs(cx, &self.valid_idents, attrs);
if let hir::TraitItemKind::Fn(ref sig, ..) = item.kind {
if !in_external_macro(cx.tcx.sess, item.span) {
- lint_for_missing_headers(cx, item.hir_id(), item.span, sig, headers, None, None);
+ lint_for_missing_headers(cx, item.def_id, item.span, sig, headers, None, None);
}
}
}
panic_span: None,
};
fpu.visit_expr(&body.value);
- lint_for_missing_headers(
- cx,
- item.hir_id(),
- item.span,
- sig,
- headers,
- Some(body_id),
- fpu.panic_span,
- );
+ lint_for_missing_headers(cx, item.def_id, item.span, sig, headers, Some(body_id), fpu.panic_span);
}
}
}
fn lint_for_missing_headers<'tcx>(
cx: &LateContext<'tcx>,
- hir_id: hir::HirId,
+ def_id: LocalDefId,
span: impl Into<MultiSpan> + Copy,
sig: &hir::FnSig<'_>,
headers: DocHeaders,
body_id: Option<hir::BodyId>,
panic_span: Option<Span>,
) {
- if !cx.access_levels.is_exported(hir_id) {
+ if !cx.access_levels.is_exported(def_id) {
return; // Private functions do not require doc comments
}
+
+ // do not lint if any parent has `#[doc(hidden)]` attribute (#7347)
+ if cx
+ .tcx
+ .hir()
+ .parent_iter(cx.tcx.hir().local_def_id_to_hir_id(def_id))
+ .any(|(id, _node)| is_doc_hidden(cx.tcx.hir().attrs(id)))
+ {
+ return;
+ }
+
if !headers.safety && sig.header.unsafety == hir::Unsafety::Unsafe {
span_lint(
cx,
);
}
if !headers.errors {
- if is_type_diagnostic_item(cx, return_ty(cx, hir_id), sym::result_type) {
+ let hir_id = cx.tcx.hir().local_def_id_to_hir_id(def_id);
+ if is_type_diagnostic_item(cx, return_ty(cx, hir_id), sym::Result) {
span_lint(
cx,
MISSING_ERRORS_DOC,
if let ty::Opaque(_, subs) = ret_ty.kind();
if let Some(gen) = subs.types().next();
if let ty::Generator(_, subs, _) = gen.kind();
- if is_type_diagnostic_item(cx, subs.as_generator().return_ty(), sym::result_type);
+ if is_type_diagnostic_item(cx, subs.as_generator().return_ty(), sym::Result);
then {
span_lint(
cx,
}
fn check_attrs<'a>(cx: &LateContext<'_>, valid_idents: &FxHashSet<String>, attrs: &'a [Attribute]) -> DocHeaders {
+ use pulldown_cmark::{BrokenLink, CowStr, Options};
+ /// We don't want the parser to choke on intra doc links. Since we don't
+ /// actually care about rendering them, just pretend that all broken links are
+ /// point to a fake address.
+ #[allow(clippy::unnecessary_wraps)] // we're following a type signature
+ fn fake_broken_link_callback<'a>(_: BrokenLink<'_>) -> Option<(CowStr<'a>, CowStr<'a>)> {
+ Some(("fake".into(), "fake".into()))
+ }
+
let mut doc = String::new();
let mut spans = vec![];
};
}
- let parser = pulldown_cmark::Parser::new(&doc).into_offset_iter();
+ let mut cb = fake_broken_link_callback;
+
+ let parser =
+ pulldown_cmark::Parser::new_with_broken_link_callback(&doc, Options::empty(), Some(&mut cb)).into_offset_iter();
// Iterate over all `Events` and combine consecutive events into one
let events = parser.coalesce(|previous, current| {
use pulldown_cmark::Event::Text;
spans: &[(usize, Span)],
) -> DocHeaders {
// true if a safety header was found
- use pulldown_cmark::CodeBlockKind;
use pulldown_cmark::Event::{
Code, End, FootnoteReference, HardBreak, Html, Rule, SoftBreak, Start, TaskListMarker, Text,
};
- use pulldown_cmark::Tag::{CodeBlock, Heading, Link};
+ use pulldown_cmark::Tag::{CodeBlock, Heading, Item, Link, Paragraph};
+ use pulldown_cmark::{CodeBlockKind, CowStr};
let mut headers = DocHeaders {
safety: false,
let mut in_heading = false;
let mut is_rust = false;
let mut edition = None;
+ let mut ticks_unbalanced = false;
+ let mut text_to_check: Vec<(CowStr<'_>, Span)> = Vec::new();
+ let mut paragraph_span = spans.get(0).expect("function isn't called if doc comment is empty").1;
for (event, range) in events {
match event {
Start(CodeBlock(ref kind)) => {
},
Start(Link(_, url, _)) => in_link = Some(url),
End(Link(..)) => in_link = None,
- Start(Heading(_)) => in_heading = true,
- End(Heading(_)) => in_heading = false,
+ Start(Heading(_) | Paragraph | Item) => {
+ if let Start(Heading(_)) = event {
+ in_heading = true;
+ }
+ ticks_unbalanced = false;
+ let (_, span) = get_current_span(spans, range.start);
+ paragraph_span = first_line_of_span(cx, span);
+ },
+ End(Heading(_) | Paragraph | Item) => {
+ if let End(Heading(_)) = event {
+ in_heading = false;
+ }
+ if ticks_unbalanced {
+ span_lint_and_help(
+ cx,
+ DOC_MARKDOWN,
+ paragraph_span,
+ "backticks are unbalanced",
+ None,
+ "a backtick may be missing a pair",
+ );
+ } else {
+ for (text, span) in text_to_check {
+ check_text(cx, valid_idents, &text, span);
+ }
+ }
+ text_to_check = Vec::new();
+ },
Start(_tag) | End(_tag) => (), // We don't care about other tags
Html(_html) => (), // HTML is weird, just ignore it
SoftBreak | HardBreak | TaskListMarker(_) | Code(_) | Rule => (),
FootnoteReference(text) | Text(text) => {
- if Some(&text) == in_link.as_ref() {
+ let (begin, span) = get_current_span(spans, range.start);
+ paragraph_span = paragraph_span.with_hi(span.hi());
+ ticks_unbalanced |= text.contains('`') && !in_code;
+ if Some(&text) == in_link.as_ref() || ticks_unbalanced {
// Probably a link of the form `<http://example.com>`
// Which are represented as a link to "http://example.com" with
// text "http://example.com" by pulldown-cmark
continue;
}
- headers.safety |= in_heading && text.trim() == "Safety";
- headers.errors |= in_heading && text.trim() == "Errors";
- headers.panics |= in_heading && text.trim() == "Panics";
- let index = match spans.binary_search_by(|c| c.0.cmp(&range.start)) {
- Ok(o) => o,
- Err(e) => e - 1,
- };
- let (begin, span) = spans[index];
+ let trimmed_text = text.trim();
+ headers.safety |= in_heading && trimmed_text == "Safety";
+ headers.safety |= in_heading && trimmed_text == "Implementation safety";
+ headers.safety |= in_heading && trimmed_text == "Implementation Safety";
+ headers.errors |= in_heading && trimmed_text == "Errors";
+ headers.panics |= in_heading && trimmed_text == "Panics";
if in_code {
if is_rust {
let edition = edition.unwrap_or_else(|| cx.tcx.sess.edition());
} else {
// Adjust for the beginning of the current `Event`
let span = span.with_lo(span.lo() + BytePos::from_usize(range.start - begin));
-
- check_text(cx, valid_idents, &text, span);
+ text_to_check.push((text, span));
}
},
}
headers
}
+fn get_current_span(spans: &[(usize, Span)], idx: usize) -> (usize, Span) {
+ let index = match spans.binary_search_by(|c| c.0.cmp(&idx)) {
+ Ok(o) => o,
+ Err(e) => e - 1,
+ };
+ spans[index]
+}
+
fn check_code(cx: &LateContext<'_>, text: &str, edition: Edition, span: Span) {
- fn has_needless_main(code: &str, edition: Edition) -> bool {
+ fn has_needless_main(code: String, edition: Edition) -> bool {
rustc_driver::catch_fatal_errors(|| {
- rustc_span::with_session_globals(edition, || {
- let filename = FileName::anon_source_code(code);
+ rustc_span::create_session_globals_then(edition, || {
+ let filename = FileName::anon_source_code(&code);
let sm = Lrc::new(SourceMap::new(FilePathMapping::empty()));
- let emitter = EmitterWriter::new(box io::sink(), None, false, false, false, None, false);
- let handler = Handler::with_emitter(false, None, box emitter);
+ let emitter = EmitterWriter::new(Box::new(io::sink()), None, false, false, false, None, false);
+ let handler = Handler::with_emitter(false, None, Box::new(emitter));
let sess = ParseSess::with_span_handler(handler, sm);
- let mut parser = match maybe_new_parser_from_source_str(&sess, filename, code.into()) {
+ let mut parser = match maybe_new_parser_from_source_str(&sess, filename, code) {
Ok(p) => p,
Err(errs) => {
for mut err in errs {
.unwrap_or_default()
}
- if has_needless_main(text, edition) {
+ // Because of the global session, we need to create a new session in a different thread with
+ // the edition we need.
+ let text = text.to_owned();
+ if thread::spawn(move || has_needless_main(text, edition))
+ .join()
+ .expect("thread::spawn failed")
+ {
span_lint(cx, NEEDLESS_DOCTEST_MAIN, span, "needless `fn main` in doctest");
}
}
span.lo() + BytePos::from_usize(offset),
span.lo() + BytePos::from_usize(offset + word.len()),
span.ctxt(),
+ span.parent(),
);
check_word(cx, word, span);
// check for `unwrap`
if let Some(arglists) = method_chain_args(expr, &["unwrap"]) {
let reciever_ty = self.typeck_results.expr_ty(&arglists[0][0]).peel_refs();
- if is_type_diagnostic_item(self.cx, reciever_ty, sym::option_type)
- || is_type_diagnostic_item(self.cx, reciever_ty, sym::result_type)
+ if is_type_diagnostic_item(self.cx, reciever_ty, sym::Option)
+ || is_type_diagnostic_item(self.cx, reciever_ty, sym::Result)
{
self.panic_span = Some(expr.span);
}
projects / rust.git / blobdiff