I understand that if (at least one of) a tuple variant's fields is documented, we need a place to put that documentation. But if not this just adds superfluous noise. Especially if you have a lot of tuple enum variants with undocumented fields it becomes very noisy very quickly. As a real world example from one of my codebases:
pub enum RotationPolicy {
/// Only rotate when [`RotatingFileWriter::rotate`] is called.
Manual,
/// Rotate when the active file exceeds this many bytes.
SizeLimit(usize),
/// Rotate periodically.
Periodically(Period),
/// Rotate both periodically and whenever the size limit is exceeded.
SizeLimitAndPeriodically(usize, Period),
/// A custom callback to determine when to rotate. Called after every write
/// with the current active file size and age.
Custom(Box<dyn FnMut(usize, Duration) -> bool>),
}How it currently looks:
And with the superfluous sections removed:
I think we should get rid of any "Tuple Fields of Variant" section if that variants' fields are undocumented. It only adds noise and makes the documentation less readable in my opinion.
I understand that if (at least one of) a tuple variant's fields is documented, we need a place to put that documentation. But if not this just adds superfluous noise. Especially if you have a lot of tuple enum variants with undocumented fields it becomes very noisy very quickly. As a real world example from one of my codebases:
How it currently looks:
And with the superfluous sections removed:
I think we should get rid of any "Tuple Fields of Variant" section if that variants' fields are undocumented. It only adds noise and makes the documentation less readable in my opinion.