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

Message-ID: <f99c8f3b-95eb-4e68-af25-62a5a0a8de64@proton.me>
Date: Wed, 25 Oct 2023 14:54:42 +0000
From: Benno Lossin <benno.lossin@...ton.me>
To: FUJITA Tomonori <fujita.tomonori@...il.com>
Cc: 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 25.10.23 12:57, FUJITA Tomonori wrote:
> On Wed, 25 Oct 2023 07:24:00 +0000
> Benno Lossin <benno.lossin@...ton.me> wrote:
> 
>>> /// PHY state machine states.
>>> ///
>>> /// Corresponds to the kernel's
>>> /// [`enum phy_state`](../../../../../networking/kapi.html#c.phy_state).
>>> ///
>>> /// Some of PHY drivers access to the state of PHY's software state machine.
>>
>> That is one way, another would be to do:
> 
> This looks nicer.
> 
>> /// 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

-- 
Cheers,
Benno