Re: [PATCH net-next v1 1/2] rust: add delay abstraction

[Thomas Gleixner <tglx@linutronix.de>]

On Wed, Oct 02 2024 at 15:21, Miguel Ojeda wrote:
> On Wed, Oct 2, 2024 at 2:51 PM Andrew Lunn <andrew@lunn.ch> wrote:
>> Maybe this is my background as a C programmer, with its sloppy type
>> system, but i prefer to have this very clear, maybe redundantly
>> stating it in words in addition to the signature.
>
> The second part of my message was about the signature point you made,
> i.e. not about the units. So I am not sure if you are asking here to
> re-state the types of parameters in every function's docs -- what do
> you gain from that in common cases?
>
> We also don't repeat every parameter in a bullet list inside the
> documentation to explain each parameter, unless a parameter needs it
> for a particular reason. In general, the stronger/stricter your
> types/signatures are, and the better documented your types are, the
> less "extra notes" in every function you need.
>
> For instance, if you see `int` in a signature, then you very likely
> need documentation to understand how the argument works because `int`
> is way too general (e.g. it is likely it admits cases you are not
> supposed to use). However, if you see `Duration`, then you already
> know the answer to the units question.
>
> Thus, in a way, we are factoring out documentation to a single place,
> thus making them simpler/easier/lighter -- so you can see it as a way
> to scale writing docs! :)
>
> That is also why carrying as much information in the signature also
> helps with docs, and not just with having the compiler catch mistakes
> for us.

I completely agree.

'delay(Duration d)' does not need explanation for @d unless there is a
restriction for the valid range of @d. @d is explained in the
documentation of Duration.

That's not any different in C, when the function argument is a pointer
to a complex struct. Nobody would even think about explaining the struct
members in the documentation of the function which has that struct
pointer argument. No, you need to go to the struct declaration to figure
it out.

Redundant documentation is actually bad, because any changes to the type
will inevitably lead to stale documentation at the usage site. The
kernel is full of this.

I havent's seen the actual patches as they were sent to netdev for
whatever reason. There is a larger rework of delay.h going on:

  https://lore.kernel.org/all/20240911-devel-anna-maria-b4-timers-flseep-v2-0-b0d3f33ccfe0@linutronix.de/

V3 will be coming early next week. So please look at V2 if you have any
constraints vs. the rust implementation.

Thanks,

        tglx