Skip to content

Commit d638563

Browse files
Add lint for doc without codeblocks
1 parent 607243b commit d638563

File tree

5 files changed

+94
-29
lines changed

5 files changed

+94
-29
lines changed

src/librustc/lint/builtin.rs

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -312,6 +312,12 @@ declare_lint! {
312312
"warn about documentation intra links resolution failure"
313313
}
314314

315+
declare_lint! {
316+
pub MISSING_DOC_ITEM_CODE_EXAMPLE,
317+
Allow,
318+
"warn about missing code example in an item's documentation"
319+
}
320+
315321
declare_lint! {
316322
pub WHERE_CLAUSES_OBJECT_SAFETY,
317323
Warn,
@@ -408,6 +414,7 @@ impl LintPass for HardwiredLints {
408414
DUPLICATE_ASSOCIATED_TYPE_BINDINGS,
409415
DUPLICATE_MACRO_EXPORTS,
410416
INTRA_DOC_LINK_RESOLUTION_FAILURE,
417+
MISSING_DOC_CODE_EXAMPLES,
411418
WHERE_CLAUSES_OBJECT_SAFETY,
412419
PROC_MACRO_DERIVE_RESOLUTION_FALLBACK,
413420
MACRO_USE_EXTERN_CRATE,

src/librustdoc/core.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -348,12 +348,14 @@ pub fn run_core(search_paths: SearchPaths,
348348
let intra_link_resolution_failure_name = lint::builtin::INTRA_DOC_LINK_RESOLUTION_FAILURE.name;
349349
let warnings_lint_name = lint::builtin::WARNINGS.name;
350350
let missing_docs = rustc_lint::builtin::MISSING_DOCS.name;
351+
let missing_doc_example = rustc_lint::builtin::MISSING_DOC_ITEM_CODE_EXAMPLE.name;
351352

352353
// In addition to those specific lints, we also need to whitelist those given through
353354
// command line, otherwise they'll get ignored and we don't want that.
354355
let mut whitelisted_lints = vec![warnings_lint_name.to_owned(),
355356
intra_link_resolution_failure_name.to_owned(),
356-
missing_docs.to_owned()];
357+
missing_docs.to_owned(),
358+
missing_doc_example.to_owned()];
357359

358360
whitelisted_lints.extend(cmd_lints.iter().map(|(lint, _)| lint).cloned());
359361

src/librustdoc/html/markdown.rs

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -532,8 +532,10 @@ impl fmt::Display for TestableCodeError {
532532
}
533533
}
534534

535-
pub fn find_testable_code(
536-
doc: &str, tests: &mut test::Collector, error_codes: ErrorCodes,
535+
pub fn find_testable_code<T: test::Tester>(
536+
doc: &str,
537+
tests: &mut T,
538+
error_codes: ErrorCodes,
537539
) -> Result<(), TestableCodeError> {
538540
let mut parser = Parser::new(doc);
539541
let mut prev_offset = 0;

src/librustdoc/passes/collect_intra_doc_links.rs

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ use std::ops::Range;
2424

2525
use core::DocContext;
2626
use fold::DocFolder;
27-
use html::markdown::markdown_links;
27+
use html::markdown::{find_testable_code, markdown_links, ErrorCodes, LangString};
28+
2829
use passes::Pass;
2930

3031
pub const COLLECT_INTRA_DOC_LINKS: Pass =
@@ -211,6 +212,43 @@ impl<'a, 'tcx, 'rcx, 'cstore> LinkCollector<'a, 'tcx, 'rcx, 'cstore> {
211212
}
212213
}
213214

215+
fn look_for_tests<'a, 'tcx: 'a, 'rcx: 'a, 'cstore: 'rcx>(
216+
cx: &'a DocContext<'a, 'tcx, 'rcx, 'cstore>,
217+
dox: &str,
218+
item: &Item,
219+
) {
220+
if (item.is_mod() && cx.tcx.hir.as_local_node_id(item.def_id).is_none()) ||
221+
cx.as_local_node_id(item.def_id).is_none() {
222+
// If non-local, no need to check anything.
223+
return;
224+
}
225+
226+
struct Tests {
227+
found_tests: usize,
228+
}
229+
230+
impl ::test::Tester for Tests {
231+
fn add_test(&mut self, _: String, _: LangString, _: usize) {
232+
self.found_tests += 1;
233+
}
234+
}
235+
236+
let mut tests = Tests {
237+
found_tests: 0,
238+
};
239+
240+
if find_testable_code(&dox, &mut tests, ErrorCodes::No).is_ok() {
241+
if tests.found_tests == 0 {
242+
let mut diag = cx.tcx.struct_span_lint_node(
243+
lint::builtin::MISSING_DOC_ITEM_CODE_EXAMPLE,
244+
NodeId::new(0),
245+
span_of_attrs(&item.attrs),
246+
"Missing code example in this documentation");
247+
diag.emit();
248+
}
249+
}
250+
}
251+
214252
impl<'a, 'tcx, 'rcx, 'cstore> DocFolder for LinkCollector<'a, 'tcx, 'rcx, 'cstore> {
215253
fn fold_item(&mut self, mut item: Item) -> Option<Item> {
216254
let item_node_id = if item.is_mod() {
@@ -273,6 +311,12 @@ impl<'a, 'tcx, 'rcx, 'cstore> DocFolder for LinkCollector<'a, 'tcx, 'rcx, 'cstor
273311
let cx = self.cx;
274312
let dox = item.attrs.collapsed_doc_value().unwrap_or_else(String::new);
275313

314+
look_for_tests(&cx, &dox, &item);
315+
316+
if !UnstableFeatures::from_environment().is_nightly_build() {
317+
return None;
318+
}
319+
276320
for (ori_link, link_range) in markdown_links(&dox) {
277321
// bail early for real links
278322
if ori_link.contains('/') {

src/librustdoc/test.rs

Lines changed: 35 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,14 @@ fn partition_source(s: &str) -> (String, String) {
466466
(before, after)
467467
}
468468

469+
pub trait Tester {
470+
fn add_test(&mut self, test: String, config: LangString, line: usize);
471+
fn get_line(&self) -> usize {
472+
0
473+
}
474+
fn register_header(&mut self, _name: &str, _level: u32) {}
475+
}
476+
469477
pub struct Collector {
470478
pub tests: Vec<testing::TestDescAndFn>,
471479

@@ -534,7 +542,31 @@ impl Collector {
534542
format!("{} - {} (line {})", filename, self.names.join("::"), line)
535543
}
536544

537-
pub fn add_test(&mut self, test: String, config: LangString, line: usize) {
545+
pub fn set_position(&mut self, position: Span) {
546+
self.position = position;
547+
}
548+
549+
fn get_filename(&self) -> FileName {
550+
if let Some(ref source_map) = self.source_map {
551+
let filename = source_map.span_to_filename(self.position);
552+
if let FileName::Real(ref filename) = filename {
553+
if let Ok(cur_dir) = env::current_dir() {
554+
if let Ok(path) = filename.strip_prefix(&cur_dir) {
555+
return path.to_owned().into();
556+
}
557+
}
558+
}
559+
filename
560+
} else if let Some(ref filename) = self.filename {
561+
filename.clone().into()
562+
} else {
563+
FileName::Custom("input".to_owned())
564+
}
565+
}
566+
}
567+
568+
impl Tester for Collector {
569+
fn add_test(&mut self, test: String, config: LangString, line: usize) {
538570
let filename = self.get_filename();
539571
let name = self.generate_name(line, &filename);
540572
let cfgs = self.cfgs.clone();
@@ -588,7 +620,7 @@ impl Collector {
588620
});
589621
}
590622

591-
pub fn get_line(&self) -> usize {
623+
fn get_line(&self) -> usize {
592624
if let Some(ref source_map) = self.source_map {
593625
let line = self.position.lo().to_usize();
594626
let line = source_map.lookup_char_pos(BytePos(line as u32)).line;
@@ -598,29 +630,7 @@ impl Collector {
598630
}
599631
}
600632

601-
pub fn set_position(&mut self, position: Span) {
602-
self.position = position;
603-
}
604-
605-
fn get_filename(&self) -> FileName {
606-
if let Some(ref source_map) = self.source_map {
607-
let filename = source_map.span_to_filename(self.position);
608-
if let FileName::Real(ref filename) = filename {
609-
if let Ok(cur_dir) = env::current_dir() {
610-
if let Ok(path) = filename.strip_prefix(&cur_dir) {
611-
return path.to_owned().into();
612-
}
613-
}
614-
}
615-
filename
616-
} else if let Some(ref filename) = self.filename {
617-
filename.clone().into()
618-
} else {
619-
FileName::Custom("input".to_owned())
620-
}
621-
}
622-
623-
pub fn register_header(&mut self, name: &str, level: u32) {
633+
fn register_header(&mut self, name: &str, level: u32) {
624634
if self.use_headers {
625635
// we use these headings as test names, so it's good if
626636
// they're valid identifiers.

0 commit comments

Comments
 (0)