bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #96008 - fmease:warn-on-useless-doc-hidden-on-assoc-impl-items, r=lcnr

Browse source 
Warn on unused `#[doc(hidden)]` attributes on trait impl items

[Zulip conversation](https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/.E2.9C.94.20Validy.20checks.20for.20.60.23.5Bdoc.28hidden.29.5D.60).

Whether an associated item in a trait impl is shown or hidden in the documentation entirely depends on the corresponding item in the trait declaration. Rustdoc completely ignores `#[doc(hidden)]` attributes on impl items. No error or warning is emitted:

```rust
pub trait Tr { fn f(); }
pub struct Ty;
impl Tr for Ty { #[doc(hidden)] fn f() {} }
//               ^^^^^^^^^^^^^^ ignored by rustdoc and currently
//                              no error or warning issued
```

This may lead users to the wrong belief that the attribute has an effect. In fact, several such cases are found in the standard library (I've removed all of them in this PR).
There does not seem to exist any incentive to allow this in the future either: Impl'ing a trait for a type means the type *fully* conforms to its API. Users can add `#[doc(hidden)]` to the whole impl if they want to hide the implementation or add the attribute to the corresponding associated item in the trait declaration to hide the specific item. Hiding an implementation of an associated item does not make much sense: The associated item can still be found on the trait page.

This PR emits the warn-by-default lint `unused_attribute` for this case with a future-incompat warning.

`@rustbot` label T-compiler T-rustdoc A-lint
This commit is contained in:
Matthias Krüger 2022-05-09 18:45:36 +02:00 • committed by GitHub
commit 6c8001b85c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
18 changed files with 225 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

1
library/core/src/convert/num.rs
View file

@ -25,7 +25,6 @@ macro_rules! impl_float_to_int {
$(
#[unstable(feature = "convert_float_to_int", issue = "67057")]
impl FloatToInt<$Int> for $Float {
#[doc(hidden)]
#[inline]
unsafe fn to_int_unchecked(self) -> $Int {
// SAFETY: the safety contract must be upheld by the caller.

1
library/core/src/iter/adapters/cloned.rs
View file

@ -60,7 +60,6 @@ where
self.it.map(T::clone).fold(init, f)
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> T
where
Self: TrustedRandomAccessNoCoerce,

1
library/core/src/iter/adapters/copied.rs
View file

@ -81,7 +81,6 @@ where
self.it.advance_by(n)
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> T
where
Self: TrustedRandomAccessNoCoerce,

1
library/core/src/iter/adapters/enumerate.rs
View file

@ -128,7 +128,6 @@ where
}
#[rustc_inherit_overflow_checks]
#[doc(hidden)]
#[inline]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> <Self as Iterator>::Item
where

1
library/core/src/iter/adapters/fuse.rs
View file

@ -129,7 +129,6 @@ where
}
#[inline]
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item
where
Self: TrustedRandomAccessNoCoerce,

1
library/core/src/iter/adapters/map.rs
View file

@ -124,7 +124,6 @@ where
self.iter.fold(init, map_fold(self.f, g))
}
#[doc(hidden)]
#[inline]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> B
where

1
library/core/src/iter/adapters/zip.rs
View file

@ -95,7 +95,6 @@ where
}
#[inline]
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item
where
Self: TrustedRandomAccessNoCoerce,

1
library/core/src/iter/range.rs
View file

@ -752,7 +752,6 @@ impl<A: Step> Iterator for ops::Range<A> {
}
#[inline]
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item
where
Self: TrustedRandomAccessNoCoerce,

11
library/core/src/slice/iter.rs
View file

@ -1322,7 +1322,6 @@ impl<'a, T> Iterator for Windows<'a, T> {
}
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
// SAFETY: since the caller guarantees that `i` is in bounds,
// which means that `i` cannot overflow an `isize`, and the
@ -1478,7 +1477,6 @@ impl<'a, T> Iterator for Chunks<'a, T> {
}
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let start = idx * self.chunk_size;
// SAFETY: the caller guarantees that `i` is in bounds,
@ -1657,7 +1655,6 @@ impl<'a, T> Iterator for ChunksMut<'a, T> {
}
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let start = idx * self.chunk_size;
// SAFETY: see comments for `Chunks::__iterator_get_unchecked`.
@ -1830,7 +1827,6 @@ impl<'a, T> Iterator for ChunksExact<'a, T> {
self.next_back()
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let start = idx * self.chunk_size;
// SAFETY: mostly identical to `Chunks::__iterator_get_unchecked`.
@ -1984,7 +1980,6 @@ impl<'a, T> Iterator for ChunksExactMut<'a, T> {
self.next_back()
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let start = idx * self.chunk_size;
// SAFETY: see comments for `ChunksMut::__iterator_get_unchecked`.
@ -2248,7 +2243,6 @@ impl<'a, T, const N: usize> Iterator for ArrayChunks<'a, T, N> {
self.iter.last()
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, i: usize) -> &'a [T; N] {
// SAFETY: The safety guarantees of `__iterator_get_unchecked` are
// transferred to the caller.
@ -2367,7 +2361,6 @@ impl<'a, T, const N: usize> Iterator for ArrayChunksMut<'a, T, N> {
self.iter.last()
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, i: usize) -> &'a mut [T; N] {
// SAFETY: The safety guarantees of `__iterator_get_unchecked` are transferred to
// the caller.
@ -2520,7 +2513,6 @@ impl<'a, T> Iterator for RChunks<'a, T> {
}
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let end = self.v.len() - idx * self.chunk_size;
let start = match end.checked_sub(self.chunk_size) {
@ -2689,7 +2681,6 @@ impl<'a, T> Iterator for RChunksMut<'a, T> {
}
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let end = self.v.len() - idx * self.chunk_size;
let start = match end.checked_sub(self.chunk_size) {
@ -2856,7 +2847,6 @@ impl<'a, T> Iterator for RChunksExact<'a, T> {
self.next_back()
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let end = self.v.len() - idx * self.chunk_size;
let start = end - self.chunk_size;
@ -3016,7 +3006,6 @@ impl<'a, T> Iterator for RChunksExactMut<'a, T> {
self.next_back()
}
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
let end = self.v.len() - idx * self.chunk_size;
let start = end - self.chunk_size;

1
library/core/src/slice/iter/macros.rs
View file

@ -325,7 +325,6 @@ macro_rules! iterator {
None
}
#[doc(hidden)]
#[inline]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
// SAFETY: the caller must guarantee that `i` is in bounds of

1
library/core/src/str/iter.rs
View file

@ -298,7 +298,6 @@ impl Iterator for Bytes<'_> {
}
#[inline]
#[doc(hidden)]
unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> u8 {
// SAFETY: the caller must uphold the safety contract
// for `Iterator::__iterator_get_unchecked`.