linux-kernel - Re: [PATCH 11/13] rust: kernel: add doclinks with html tags

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]

Date: Wed, 17 Jan 2024 10:10:29 +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>,
	Martin Rodriguez Reboredo <yakoyoku@...il.com>
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

> > [...]
> > @@ -14,7 +14,8 @@
> >     /// Byte string without UTF-8 validity guarantee.
> >   ///
> > -/// `BStr` is simply an alias to `[u8]`, but has a more evident semantical meaning.
> > +/// `BStr` is simply an alias to <code>[[u8]]</code>, but has a more evident
> > +/// semantical meaning.

> Isn't there a way to escape square brackets with backslashes with
> mbBook? Like `\[qux\]` or something? I ask this because this affects the
> readability of the doc comment so if that could be omitted it'll be
> really good.

Here are the things that I tried that did not produce a link:
[`[u8]`], `[[u8]]`, `[\[u8\]]`, `\[u8\]`, [`\[u8\]`], `[[u8](u8)]`,
`[[u8][u8]]`,

This results in a link, but it includes the square brackets:
[`[u8]`][u8], [`[u8]`](u8)

This results in a link that only includes the `u8`, but it is not
formatted as code:
[[u8]]

The only other examples of linked slices that I found are in the
standard library [1].

My assuption is that crate documentation is much more often consumed in
its rendered form, which is why I think the reduced readability is ok.
However, if that is not the case this change might be a bad idea.

[1]: https://doc.rust-lang.org/src/alloc/ffi/c_str.rs.html#58