On 11/7/25 5:55 PM, Alexandre Courbot wrote:
> On Sun Nov 2, 2025 at 12:33 PM JST, John Hubbard wrote:
>> On 11/1/25 7:41 PM, Alexandre Courbot wrote:
>>> On Sun Nov 2, 2025 at 9:34 AM JST, John Hubbard wrote:
>>>> On 10/29/25 7:05 AM, Alexandre Courbot wrote:
>> ...
>>
>>> We can always add doccomments in the macro, as in the patch below. These
>>> will be displayed by LSP when one highlights or tries to use one of
>>> these constants.
>>>
>>> If you think that's adequate, I will send a patch.
>>>
>>> --- a/drivers/gpu/nova-core/bitfield.rs
>>> +++ b/drivers/gpu/nova-core/bitfield.rs
>>> @@ -249,7 +249,10 @@ impl $name {
>>> { $process:expr } $prim_type:tt $to_type:ty => $res_type:ty
>>> $(, $comment:literal)?;
>>> ) => {
>>> ::kernel::macros::paste!(
>>> + /// Inclusive range of the bits covered by this field.
>>> const [<$field:upper _RANGE>]: ::core::ops::RangeInclusive<u8> =
>>> $lo..=$hi;
>>
>> Will that let people know that they'll see something like
>> IMPLEMENTATION_RANGE() for a corresponding .implementation field?
>>
>> I'm hoping we can somehow create clear and plain documentation for
>> the various functions that the macro generates.
>
> I did try to generate better documentation for these using the `#doc`
> directive, actually posted the patch by mistake so I might as well link
> to it:
>
> https://lore.kernel.org/rust-for-linux/[email protected]/
>
> Unfortunately, the final documentation does not appear with
> rust-analyzer/LSP, which drastically limits its usefulness. :/
Thanks for trying that out. I'm starting to believe that in 2025,
we maybe just need to fall back to writing comments directly near
the macro implementation code, and that way there is something
for people to read.
That would still be a significant improvement over visually parsing
the macro implementation, in order to deduce the new function names
that are being pasted together. I think...
thanks,
--
John Hubbard
