Consider treating docsrs doc cfg as hidden by default #148551
Description
As a followup to #138907, consider making a special case for cfg(docsrs) as if every crate were written with #![doc(auto_cfg(hide(docsrs)))] at the crate root. It pretty much never makes sense for rustdoc to render "Available on docsrs only".
An example usage of cfg(docsrs) is in the following idiom that works around impl Trait<'a> not having a syntax to express that the opaque type either has no Drop or allows the lifetime to dangle during drop (unsafe impl<#[may_dangle] 'a> Drop for ConcreteType<'a>).
#![cfg_attr(docsrs, feature(doc_cfg))]
#![allow(mismatched_lifetime_syntaxes)]
macro_rules! return_impl_trait {
(
$(#[$attr:meta])*
$vis:vis fn $name:ident $args:tt -> $impl_trait:ty [$concrete:ty] $body:block
) => {
#[cfg(not(docsrs))]
$(#[$attr])*
$vis fn $name $args -> $concrete $body
#[cfg(docsrs)]
$(#[$attr])*
$vis fn $name $args -> $impl_trait $body
};
}
pub struct Generics;
pub struct LifetimeParam;
impl Generics {
return_impl_trait! {
pub fn lifetimes(&self) -> impl Iterator<Item = &LifetimeParam> [iter::Lifetimes] {
iter::Lifetimes(&[/*...*/])
}
}
}
mod iter {
use crate::LifetimeParam;
pub struct Lifetimes<'a>(pub(crate) &'a [LifetimeParam]);
impl<'a> Iterator for Lifetimes<'a> {
type Item = &'a LifetimeParam;
fn next(&mut self) -> Option<Self::Item> {
let (first, rest) = self.0.split_first()?;
self.0 = rest;
Some(first)
}
}
}