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: <20240118091437.25001-1-kernel@valentinobst.de>
Date: Thu, 18 Jan 2024 10:14:37 +0100
From: Valentin Obst <kernel@...entinobst.de>
To: Miguel Ojeda <ojeda@...nel.org>,
	Alex Gaynor <alex.gaynor@...il.com>,
	Wedson Almeida Filho <wedsonaf@...il.com>,
	Trevor Gross <tmgross@...ch.edu>
Cc: Boqun Feng <boqun.feng@...il.com>,
	Gary Guo <gary@...yguo.net>,
	Björn Roy Baron <bjorn3_gh@...tonmail.com>,
	Benno Lossin <benno.lossin@...ton.me>,
	Andreas Hindborg <a.hindborg@...sung.com>,
	Alice Ryhl <aliceryhl@...gle.com>,
	rust-for-linux@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Valentin Obst <kernel@...entinobst.de>
Subject: Re: [PATCH 11/13] rust: kernel: add doclinks with html tags

> Std sometimes does something like this, which links to the slice primitive.
>
>     [`&[u8]`](prim@...ce)

This would indeed link `&[u8]` to the slice type. But I agree, both,
linking to slice and to `u8` is not necessary as it is common knowledge.
However, if it is a slice over a more complicated/custom type it might
be worth linking to it, and in that case the 'code' tag syntax would be
the only option we have at the moment.

> What exactly is going on with Arc, is it not getting linked correctly
> when it has generics? I don't quite follow what <code> does.

In this case it is about the `&`:

<code>&[`Arc<T>`]</code>

Here, `&Arc<T>` is formatted as code, but only the `Arc<T>` is a
clickable link. While

[`&Arc<T>`]

results in:

```
/// over [&`Arc<T>`] because the latter results in a double-indirection: a pointer
    |           ^^^^^^^^ no item named `&Arc` in scope
```

using:

&[`Arc<T>`]

would result in a link, but `&` is not formatted as code. Finally,

[`&Arc<T>`](Arc)

would work but `&` is part of the clickable link now. Thus,
using the html tag here is the only way I found to get the
'cleanest' form in the rendered document.

> If rustdoc just isn't making good choices in certain places or isn't
> flexible enough, could you write issues in the Rust repo? Better to
> get inconveniences fixed upstream if possible.

I like the idea of finding a proper solution to that in rustdoc
instead of cluttering the source code with html tags. If nobody
strongly objects I'd drop the whole patch in v2 and open an issue
in the rust repo.

	- Valentin

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ