Received-SPF: pass (google.com: domain of linux-kernel+bounces-29468-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
Message-ID: <48471adc-5155-482b-83db-f1c128fe8d69@gmail.com>
Date: Wed, 17 Jan 2024 18:41:18 -0300
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH 11/13] rust: kernel: add doclinks with html tags
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: <a3856ffc-ddb9-4066-8e1d-999c8f7790e8@gmail.com>
 <20240117091029.182098-1-kernel@valentinobst.de>
Content-Language: en-US
From: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
In-Reply-To: <20240117091029.182098-1-kernel@valentinobst.de>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

On 1/17/24 06:10, Valentin Obst wrote:
>>> [...]
>>> @@ -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

I have an idea, let's just omit links to sliced types if they already
have their underlying type linked nearby. As for `[u8]` I think that we
can omit it too since readers of the documentation should be
familiarized with slices.