unclear behaviour of missing_doc_code_examples

[Geal]

Hello,
consider this code example:

#![deny(missing_docs)]
#![deny(missing_doc_code_examples)]
//! crate level doc
//! ```
//! println!("hello"):
//! ```


/// doc
///
/// ```
/// println!("hello");
/// ```
fn test() {
}

// the allow() here works as expected, but missing_doc_code_examples still complains
#[allow(missing_docs)]
mod module1 {

  fn test() {}
}

// here we want some docs but no code examples, but missing_doc_code_examples still complains
#[allow(missing_doc_code_examples)]
/// doc
mod module2 {

  /// doc
  fn test() {}
}

/// doc
///
/// ```
/// println!("hello");
/// ```
mod module3 {

  // here we want some code examples but missing_doc_code_examples does not complain
  /// doc
  fn test() {}
}

Here I would expect the following behaviour when running cargo doc:

• module1 has allow(missing_docs) so missing_doc_code_examples should be silent
• module2 has allow(missing_doc_code_examples) yet we still get errors for missing docs on module2, I think we should not
• module3 has a code example, but module3::test does not, we should get an error for the missing example on module3::test

cc @GuillaumeGomez

[GuillaumeGomez]

For module1, it's normal to get the error since both missing_doc_code_examples isn't bound to allow(missing_docs). However, for module3 it's very strange to not get anything. The strangest thing being that diagnostic is emitted there, we just don't see it.

[danieleades]

I feel like the title of this issue is slightly misleading. The behaviour is not simply unclear, it's totally broken.

[GuillaumeGomez]

@danieleades The situation should have been improved since then. Do you still have a good example of where it's totally broken so we can continue to improve the whole situation?

[danieleades]

yep.

steps to reproduce-

1. make a new crate with the following lib.rs

#![deny(missing_doc_code_examples)]

/// this function has no code examples
pub fn some_function() {}

2. build with nightly compiler

cargo +nightly build

3. observe that there are no warnings

rust: 1.49.0-nightly

[GuillaumeGomez]

It works as expected for me:

$ rustdoc --version
rustdoc 1.49.0-nightly (ffa2e7ae8 2020-10-24)
$ rustdoc foo.rs 
error: missing code example in this documentation
 --> foo.rs:1:1
  |
1 | / #![deny(missing_doc_code_examples)]
2 | |
3 | | /// this function has no code examples
4 | | pub fn some_function() {}
  | |_________________________^
  |
note: the lint level is defined here
 --> foo.rs:1:9
  |
1 | #![deny(missing_doc_code_examples)]
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^

error: missing code example in this documentation
 --> foo.rs:3:1
  |
3 | /// this function has no code examples
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: aborting due to 2 previous errors

[danieleades]

It works as expected for me:

presumably that's because you didn't follow my reproduction steps.

Is it the intended behaviour that this lint only fire if you're building documentation with rustdoc? If so, that's inconsistent with all the other lints

[GuillaumeGomez]

It's only supposed to be triggered by rustdoc indeed (my bad, didn't see you didn't use the doc command). I don't see how it's inconsistent though? It's marked as such in the lint documentation.

[danieleades]

hmm i see after some digging that it's marked as 'rustdoc only' here - https://doc.rust-lang.org/beta/rustc/lints/listing/allowed-by-default.html#missing-doc-code-examples. Mea culpa.

Perhaps there are good historical or technical reasons why this is the case, but while i'm glad it's documented, simply describing the behaviour doesn't make it consistent.

this is inconsistent in the sense that out of ~120 or so rustc lints, there are how many that are 'rustdoc-only'? 2-3?

Given that the current behaviour is documented (though unexpected) I'm now in complete support of the issue title ;)

[GuillaumeGomez]

You can see the list of the rustdoc lints there:

rust/compiler/rustc_lint/src/lib.rs

Lines 314 to 322 in 0d033de

	add_lint_group!(
	"rustdoc",
	BROKEN_INTRA_DOC_LINKS,
	PRIVATE_INTRA_DOC_LINKS,
	INVALID_CODEBLOCK_ATTRIBUTES,
	MISSING_DOC_CODE_EXAMPLES,
	PRIVATE_DOC_TESTS,
	INVALID_HTML_TAGS
	);

[GuillaumeGomez]

Seems like this issue was fixed so closing. Don't hesitate to reopen if something is still missing.