Received-SPF: pass (google.com: domain of linux-kernel+bounces-28451-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1;
Message-ID: <a3856ffc-ddb9-4066-8e1d-999c8f7790e8@gmail.com>
Date: Tue, 16 Jan 2024 22:47:24 -0300
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH 11/13] rust: kernel: add doclinks with html tags
Content-Language: en-US
To: Valentin Obst <kernel@valentinobst.de>, Miguel Ojeda <ojeda@kernel.org>,
 Alex Gaynor <alex.gaynor@gmail.com>,
 Wedson Almeida Filho <wedsonaf@gmail.com>
Cc: Boqun Feng <boqun.feng@gmail.com>, Gary Guo <gary@garyguo.net>,
 =?UTF-8?Q?Bj=C3=B6rn_Roy_Baron?= <bjorn3_gh@protonmail.com>,
 Benno Lossin <benno.lossin@proton.me>,
 Andreas Hindborg <a.hindborg@samsung.com>, Alice Ryhl
 <aliceryhl@google.com>, rust-for-linux@vger.kernel.org,
 linux-kernel@vger.kernel.org
References: <20240116160141.165951-1-kernel@valentinobst.de>
 <20240116231118.168882-1-kernel@valentinobst.de>
From: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
In-Reply-To: <20240116231118.168882-1-kernel@valentinobst.de>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

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@valentinobst.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.
> [...]