When the rustdoc::missing_doc_code_examples lint is enabled, rustdoc reports that doc comments which reference another example is missing an example. This is inconsistent with the Rust API Guidelines.

A link to an applicable example on another item may be sufficient. For example if exactly one function uses a particular type, it may be appropriate to write a single example on either the function or the type and link to it from the other.

Given the following:

/// Does the thing.
///
/// # Example
///
/// See [`crate::bar`].
pub fn foo() {}

I expected to see no warnings.

Instead, this happened:

warning: missing code example in this documentation
45 | / /// Does the thing.
46 | | ///
47 | | /// # Example
48 | | ///
...  |
54 | | ///
   | |__________________________^

Meta

rustc --version --verbose:

rustc 1.56.0-nightly (a6ece5615 2021-08-03)
binary: rustc
commit-hash: a6ece56152d8eb11e049e9fcce147b2859e12c92
commit-date: 2021-08-03
host: x86_64-unknown-linux-gnu
release: 1.56.0-nightly
LLVM version: 12.0.1