On Sun, Mar 1, 2026 at 2:23 PM Gary Guo <[email protected]> wrote: > > I started to think that the way we document invariants is problematic. For > most > of the types, the invariants mentioned does not make sense to end up in public > facing docs.
Yeah, it isn't ideal. To give some context in case it helps, so far we said that the `# Invariants` section is a special case where mentioning private fields is OK-ish if needed/helpful for a reader, even if technically it may not be "proper", i.e. leak details. One reason was that sometimes private invariants may make the type easier to understand, even if technically it is a private one. We also discussed at some point splitting invariants into public and private ones, and perhaps have `rustdoc` know about that and only render the private ones when one toggles the private items rendering (runtime toggle, which is another feature I requested -- if it is compile-time as it is the normal flag, then reading the private docs becomes too hard). Another reason was to be able to have them use doc comments and get a nice rendering output, and your suggestion of using a dummy field would work for that. I like the fact that it makes one remember to write the invariant "natively". On the other hand, it seems like something we could somehow do with changes in tooling, i.e. in `rustdoc` or Clippy (and perhaps it could be enforced rather than just be a reminder). Another bit was that sometimes the invariant, even if it applies to a private field, the type may be exposing e.g. a copy of the field through a method, and thus it is useful to know about the invariant anyway. Those cases could/should "properly" be a guarantee on the return value of that method, keeping the invariant private, though. In short, the current approach makes it easy to write for everyone, but it does have downsides and ideally we would have something better now that everyone is accustomed to writing them. Cheers, Miguel
