Document generic parameter variance in rustdoc

[SOF3]

As initially requested in rust-lang/rust#41537, variance is part of the signature of a type parameter, but it is not documented anywhere directly until the user opens the source code to recursively dig into its usages.

[fmease]

I wonder if rust-lang/rust's issue tracker would be a better fit. 🤔

There are two questions that immediately pop into my head:

1. How should we present this information to the user?
   • Should we display the variances as symbols inline, i.e. in the code block found near the top of the page? E.g., struct Struct<+'a, -'b, ·'c, +T, -U, ·V> with + covariant, - contravariant, or · or ∘ invariant, * bivariant.
     • PRO: compact
     • PRO-ish: feels familiar to Scala programmers
     • CON: illegible symbol soup
     • CON: non-Rust syntax in code blocks that try to stay very close to Rust syntax
     • CON: advanced information placed in a very central spot which isn't beginner-friendly and probably not super important to know most of the time
   • Should we generate a section / paragraph somewhere further down on the page detailing the variances?
     • PRO: the information exists for people who are looking for it without impacting the UX of the everyday user
     • PRO: can potentially link to docs explaining the concept of variance
     • PRO: similar to the way we display the memory layout of types (--show-type-layout -Zunstable-options) and object safety (rustdoc: Document lack of object safety on affected traits rust#113241)
     • CON: potential increase in page size, load or render time
     • CON: if not done right, it might be hard to piece together the wanted information
2. Opt-in, opt-out or always enabled? If it's an option, how do you set it? Via an attribute? #[doc(variance = shown|hidden)]?

[SOF3]

what about just using colors (+ hovers for colorblind readers), or other text decoration (e.g. solid/dotted underline)? it doesn't feel right for rustdoc to add its own syntax within something that seems to be Rust syntax.

[SOF3]

As for reporting it in the rust-lang/rust issue tracker, it seems this issue still involves some UI design, so it probably needs to go through the RFC process anyway? I'm not familiar with this field, so I'm just writing down the requirement without digging into the details.

Also personally I don't really "need" this feature, I just feel that rustdoc should provide this information in its output to increase developers' awareness that variance is part of the type signature.

[fmease]

it doesn't feel right for rustdoc to add its own syntax within something that seems to be Rust syntax.

Right, I fully agree. I just listed that for the sake of completeness as seen by all the CONs.

what about just using colors (+ hovers for colorblind readers), or other text decoration (e.g. solid/dotted underline)?

That's another option I haven't considered. Although I can imagine that colors and text decoration are just as distracting as obscure symbols. On top of that, there's been a move to reduce the amount of colors in rustdoc (rust-lang/rust#91480).

I actually quite like the idea of hovers … for all readers, except that they probably wouldn't be super discoverable (but that can be an advantage to some degree).

As for reporting it in the rust-lang/rust issue tracker, it seems this issue still involves some UI design, so it probably needs to go through the RFC process anyway?

rust-lang/rfcs is probably fine. I just hadn't seen any rustdoc proposals here before you opened one (excl. rustdoc RFCs ofc), people typically open rustdoc feature requests over at rust-lang/rust. Anyway.

---

I've just added this proposal to the agenda of the next rustdoc meeting.

[Diggsey]

I think a subscript could work well:

struct Foo<+T, -U>

Combined with a tooltip with more explanation.

[SOF3]

maybe the superset/subset operators are more memorizable than plus and minus?

[nikomatsakis]

I think displaying variance is a good idea, but I have a few thoughts.

1. I think we should consider something besides - and +
2. I think that struct Foo<'a, T> { x: &'a T } should treat both 'a and T as covariant (the compiler internally considers 'a to be contravariant; this will change with polonius, it's somewhat arbitrary).
3. I am considered about things being confusing. Maybe we should show nothing for covariant (the common case) and only highlight invariant (the next most common case) and contravariant.
4. Intuitively, invariant most often means that the data appears in a Cell or Mutexor some other form of interior mutability, so I wonder if we could do something like label it with mut (and, when highlighted, explain why).
5. Contravariant means it appears in a function argument, so we could label that too in some special way, though in is a common choice.

[compiler-errors]

For the record,

the compiler internally considers 'a to be contravariant

As of rust-lang/rust#107339, the compiler doesn't flip region variance anymore. See https://github.com/rust-lang/rust/pull/107339/files#diff-47d6383d2f80e4629905cc926b13600a0974819fc349e2b09772a5dab47ee4bf for example

[nikomatsakis]

Oh, ok. Great.

[GuillaumeGomez]

Kinda linked to rust-lang/rust#22108.

[fmease]

Closing in favor of rust-lang/rust#22108. Further discussions should happen over there.