On Thu Feb 19, 2026 at 3:31 PM GMT, Joel Fernandes wrote:
> On Wed, Feb 19, 2026 at 09:54:27AM +0100, Miguel Ojeda wrote:
>> If you all think something should be mentioned for practical reasons,
>> then please don't let `rustdoc` force you to not mention it, i.e.
>> please feel free to remove the square brackets if needed.
>>
>> In other words, I don't want the intra-doc links convention we have to
>> make it harder for you to write certain things exceptionally.
>
> Thanks Miguel, that's helpful! I've kept the GpuBuddyInner mention in
> the invariants but removed the square brackets to avoid the rustdoc
> warning while still providing the reference for readers.
>
> Joel
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.
Perhaps we should:
- Document invariants on specific fields as doc comments on the fields. So they
don't show up in the doc unless document-private-items is enabled.
- Invariants across multiple fields perhaps should either be documented as
normal (non-doc) comments, or we do something like:
struct Foo {
field_a: X,
field_b: Y,
// Put invariants here
_invariant: (),
}
This has an additional benefit where when you're constructing the type, you're
forced to write
Foo {
...,
_invariant: (),
}
where you're reminded that invariants exist on the type and cannot forget to
write an invariant comment.
Best,
Gary
