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]

Message-ID: <a3856ffc-ddb9-4066-8e1d-999c8f7790e8@gmail.com>
Date: Tue, 16 Jan 2024 22:47:24 -0300
From: Martin Rodriguez Reboredo <yakoyoku@...il.com>
To: Valentin Obst <kernel@...entinobst.de>, Miguel Ojeda <ojeda@...nel.org>,
 Alex Gaynor <alex.gaynor@...il.com>,
 Wedson Almeida Filho <wedsonaf@...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
Subject: Re: [PATCH 11/13] rust: kernel: add doclinks with html tags

On 1/16/24 20:11, Valentin Obst wrote:
> Add doclinks to existing documentation. Use html 'code' tags to add
> links to items that cannot be linked with the normal syntax.
> 
> The use of html tags is a tradeoff between the readability of the
> documentation's source code and the ergonomics of the generated content.
> 
> Signed-off-by: Valentin Obst <kernel@...entinobst.de>
> ---
> [...]
> @@ -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.

>   pub type BStr = [u8];
>   
>   /// Creates a new [`BStr`] from a string literal.
> [...]