rustdoc::missing_doc_code_examples inconsistent with Rust API Guidelines

[opeik]

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

[jyn514]

This is not a bug. Think of missing_doc_code_examples as a clippy restriction lint: it's not expected or recommended that everyone turns it on. If you don't think it's useful, don't use it.

Did you maybe come across this by enabling rustdoc::all? I would be open to removing missing_doc_code_examples from that lint group. clippy::all also excludes a lot of lints.

[opeik]

I enabled the lint since I think it's useful, however, I was surprised by the behaviour. Within a module there may be a few related functions which would be fine referencing an existing example. Not taking that into consideration makes this lint annoying for that use case.

[jyn514]

Within a module there may be a few related functions which would be fine referencing an existing example. Not taking that into consideration makes this lint annoying

How could rustdoc tell if you're referencing an existing example?

[opeik]

Within a module there may be a few related functions which would be fine referencing an existing example. Not taking that into consideration makes this lint annoying

How could rustdoc tell if you're referencing an existing example?

Potentially by looking at the linked item and checking if there is an example present there, instead of the current doc comment.

[peter-lyons-kehl]

(Ranting:)
On and off I've been wondering why Rustdoc doesn't have some kind of "fields/parts". Like @see, @param, @return... in JVM languages. (Of course, it would have to use syntax other than @field-name, because that's for disambiguation as per https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#path-ambiguities. And of course, some of that Rustdoc infers or gets from rustc already).

@jyn514 Is that (lack of fields/parts like @see) because it would make Rustdoc spec and implementation too complex? (Especially given that Rust is much more advanced than Java, Kotlin and possibly even Scala)? And/or was there little enough interest (in any such particular syntax/feature, or in total), or no consensus, or it's not worth doing it?

I couldn't find much (nothing obvious at https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html; some related: https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356/88: Linux kernel switched to reStructuredText, and https://internals.rust-lang.org/t/rustdoc-asciidoctor-vs-markdown/4161).

Would some simple new Rustdoc syntax not be enough, or not flexible/future-proof? For example:

• if a rustdoc paragraph consists only of word "Example" followed by an intradoc link, it would be deemed to satisfy this lint. (But, could such hijacking of words be against, or limit, i18n...?) Or
• if a link title contains word "example" (title present in the link, somehow similar to https://github.github.com/gfm/#example-494 [link](/uri "title") but applied to intradoc links). (Such a hijacking of "title" could go against, or limit, accessibility...)

But, opposite to Javadoc's @param... (or any similar approach through Asciidoctor/reStructuredText/custom-syntax), quoting @BurntSushi from https://www.reddit.com/r/rust/comments/v6rc04/comment/ibhbw1y:

• Requiring baroque markup in your documentation text to identify each parameter, the return type...
• turns a lot of doc writing into an absolute chore...
• A lot of API items just don't need to have every parameter documented in a structured way because it's obvious from the prose and/or the names...

(Update: I'll experiment, and will comment more below.)
Side note: @opeik. Your freemantle-doc has an elegant solution to this, but due to the national interests, it can't be exported...
(G'day non-Australians: Freemantle Doc(tor) is a breeze from Freemantle, Western Australia that cools down summer afternoons in Perth.)

[jyn514]

@peter-kehl I haven't read your whole comment, but if you want to propose introducing major new features, you should go through the RFC process.

[peter-lyons-kehl]

How I see the easiest solution/workaround and related problems: Sprinkling #[allow(rustdoc::missing_doc_code_examples)] around (adding it to rustdoc of functions that refer to other functions for examples) is

• wordy (which is not ergonomic), and a mixture of letters and special characters (even less ergonomic: it all adds up), and
• not carrying the intention (which is much worse than being wordy).

Because lint names (as passed to #[allow(...)]) are not (proc) macros, but special compiler symbols, we can't alias them/re-import them multiple times. So, we could workaround:

1. Have a (separate) proc macro crate (let's call it lint_allows).
2. Have an attribute macro (let's call it rustdoc_missing_doc_code_examples). The macro wouldn't take any attribute parameters. All it would do is to emit #[allow(rustdoc::missing_doc_code_examples)] before the token stream that it receives as the input (code).
3. (In your actual code) Import that macro as many times under as many names you need, for example:

• use lint_allows::rustdoc_missing_doc_code_examples as examples_linked;
• use lint_allows::rustdoc_missing_doc_code_examples as examples_none_trivial;

3. Then apply #[examples_linked], #[examples_none_trivial] (and/or as you name them).

Of course, that would not check for any link, but it would carry some intention. And, I believe that people would love it for many other lints. Like various reasons instead of one uniform #[allow(unused...)]. Side benefit: rustc would validate the (aliased) names, hence no typos - so you can grep or search for them at anytime (if you use the same aliases across your code - or you could have your own prelude-like module exporting the aliases).

The proc macro crate would export only macros with neutral names (allow_...). The developers (macro consumers) would define their aliases (indicating their intentions).

Yes, proc macros usually increase compile times. But since these macro(s) would be trivial, we may be able to implement it without Syn (to make it light). Unsure how/if that can be done (without Syn) on stable, but on nightly there are experimental API parts.

Can you think of any reverse/negative use cases? (When we'd have alias(es) to a shortcut macro emitting #[warn(...)] or #[deny(...)])?

[botahamec]

This is not a bug. Think of missing_doc_code_examples as a clippy restriction lint: it's not expected or recommended that everyone turns it on. If you don't think it's useful, don't use it.

I don't think the issue is necessarily that the current behavior is a bug, but a different set of behavior might be more useful

[botahamec]

@peter-kehl That's an interesting idea, but I think it would also be possible to just check the "Example" section to see if it contains a link, which I think would be simpler.

[peter-lyons-kehl]

Shameless promotion: All rustdoc::, (most) clippy:: and all rustc (prefixless) lints, including rustdoc::missing_doc_code_examples will be be "aliasable" multiple times with https://crates.io/crates/allow. So you could have

use allow::rustdoc::missing_doc_code_examples as allow_rustdoc_missing_docs_examples_linked;
use allow::rustdoc::missing_doc_code_examples as allow_rustdoc_missing_docs_examples_all_is_trivial;