Re: [PATCH v10 6/8] rust: gpu: Add GPU buddy allocator bindings

["Gary Guo" <gary@garyguo.net>]

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