missing_example_doc to require examples for public items

What it does

Clippy has nice lints to remind us to document errors and panics.

As I'm sure you're aware, usage examples are helpful to know how to invoke functions or construct types.

Would it be possible to re-use code from the missing_errors_doc / missing_panics_doc lints to detect missing # Example or # Examples sections in the doc comments for public functions?

This would help library developers highlight areas where we need to add usage examples.

Multiplied across many crates, could this significantly improve Rustdoc?

Advantage

• Enables Rust developers to enforce usage examples across their codebases
• Usage examples help other developers know how to use the code

Drawbacks

This could lead to more doctests being run, and therefore it might be nice to include examples of how to write doctest examples with Result in the doctest in the lint documentation, and how to skip doctests where necessary

The lint could be annoying, I'd for sure suggest it ought to be an opt-in only restriction

Example

pub fn add_2_and_2() -> Result<u8, String> {
    2u8 + 2u8
}

Could be written as:

/// # Example
/// ```
/// # use my_crate::add_2_and_2;
/// let four = add_2_and_2()?;
/// assert_eq!(four, 4u8);
/// # Ok::<(), String>(())
/// ```
pub fn add_2_and_2() -> Result<u8, String> {
    2u8 + 2u8
}

Read the existing missing_errors_doc and missing_panics_doc lints first, since the issue proposes reusing their code. Then define how an opt-in lint should detect # Example or # Examples in public function documentation, and update the lint documentation with doctest guidance and completion criteria.