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

[Martin Rodriguez Reboredo]

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.