In this code, I expected the missing_docs lint to warn about T
, but I doesn't. Why is that so?
#![deny(missing_docs)]
//! crate doc
mod mymod {
/// frobnicate
pub fn f<A: T>() {}
pub trait T {}
}
pub use mymod::f;
In this code, I expected the missing_docs lint to warn about T
, but I doesn't. Why is that so?
#![deny(missing_docs)]
//! crate doc
mod mymod {
/// frobnicate
pub fn f<A: T>() {}
pub trait T {}
}
pub use mymod::f;
Because T isn't in the public interface of the crate. If you were to pub use mymod::T;
the warning would trigger.
But when I generate the docs, T
is visible as the trait bound, and users will be confused when they can't click on it. I consider it part of the public interface.
But that's not because of the missing documentation - that's because T
is effectively non-public. If it was public, it would be clickable - just the page will be empty, aside from the formal definition.
But how will users know how to satisfy the bound, or even know what types implement T
? Not to speak of implementing T
themselves?
missing_docs
detects lack of documentation strings on items and nothing else.
It would be good to have a lint for (accidental) observable private items like this, but I don't think there is one. (Also, sometimes this exact pattern is done on purpose — it's known as “sealed traits” and prevents T
from being implemented outside the crate, which can sometimes be important for correctness or version compatibility.)
If the trait is an important part of API and not the implementation detail, then it shouldn't be effectively private.
This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.