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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CANiq72nCeGVFY_eZMhp44dqZGY1UXuEZFaJx-3OLCTk-eG=xng@mail.gmail.com>
Date: Wed, 2 Oct 2024 15:21:02 +0200
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Andrew Lunn <andrew@...n.ch>
Cc: Thomas Gleixner <tglx@...utronix.de>, FUJITA Tomonori <fujita.tomonori@...il.com>, 
	netdev@...r.kernel.org, rust-for-linux@...r.kernel.org, hkallweit1@...il.com, 
	tmgross@...ch.edu, ojeda@...nel.org, alex.gaynor@...il.com, gary@...yguo.net, 
	bjorn3_gh@...tonmail.com, benno.lossin@...ton.me, a.hindborg@...sung.com, 
	aliceryhl@...gle.com
Subject: Re: [PATCH net-next v1 1/2] rust: add delay abstraction

On Wed, Oct 2, 2024 at 2:51 PM Andrew Lunn <andrew@...n.ch> wrote:
>
> Which is better, the Rust type system catching the error, or not
> making the error in the first place because you read the documentation
> and it pointed you in the right direction?

The former, because we don't want to duplicate documentation of every
type in every function that uses a type. It does not scale, and it
would be worse for the reader of the docs as soon as you become
familiar with a given type.

Of course, there may be exceptions, but just using a type normally
should not require explaining the type itself in every function.

Also note that in e.g. the rendered docs you can jump to another type
with a single click on top of the name. In some editors, you may be
able to e.g. hover it perhaps.

> 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 hope this gives some context on why we are approaching it like this.

Cheers,
Miguel