netdev - Re: [PATCH net-next v6 1/5] rust: core abstractions for network PHY drivers

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] [day] [month] [year] [list]

Message-Id: <20231026.081913.30894727187541245.fujita.tomonori@gmail.com>
Date: Thu, 26 Oct 2023 08:19:13 +0900 (JST)
From: FUJITA Tomonori <fujita.tomonori@...il.com>
To: benno.lossin@...ton.me
Cc: fujita.tomonori@...il.com, netdev@...r.kernel.org,
 rust-for-linux@...r.kernel.org, andrew@...n.ch, tmgross@...ch.edu,
 miguel.ojeda.sandonis@...il.com, wedsonaf@...il.com, greg@...ah.com
Subject: Re: [PATCH net-next v6 1/5] rust: core abstractions for network
 PHY drivers

On Wed, 25 Oct 2023 14:54:42 +0000
Benno Lossin <benno.lossin@...ton.me> wrote:

>>> /// PHY state machine states.
>>> ///
>>> /// Corresponds to the kernel's [`enum phy_state`].
>>> ///
>>> /// Some of PHY drivers access to the state of PHY's software state machine.
>>> ///
>>> /// [`enum phy_state`]: ../../../../../networking/kapi.html#c.phy_state
>>>
>>> But as I noted before, then people who only build the rustdoc will not
>>> be able to view it. I personally would prefer to have the correct link
>>> offline, but do not know about others.
>> 
>> I prefer a link to online docs but either is fine by me. You prefer a
>> link to a header file like?
>> 
>> /// [`enum phy_state`]:  ../../../include/linux/phy.h
> 
> No. I think the header file should be mentioned for the whole
> abstraction. I personally always use [1] to search for C symbols, so
> the name suffices for me. And the documentation is (for me at least)
> less accessible (if there is a nice tool for that as well, please tell me).
> 
> [1]: https://elixir.bootlin.com/linux/latest/source

Understood. I use links to the PHY header file like other Rust
abstractions do.

IMHO, adding a link to kerneldoc would be nice but consistency in all
the abstractions is needed.