What is the RustDoc brackets syntax called?

I saw people using [`item`] in RustDoc comments to refer to lexically available items. Is this part of a Markdown superset? If so, which? I was wondering if .NET libraries such as Markdig support a way in their user pipeline for specially processing these.

It's just rustdoc flavored markdown. Doesn't have a formal name I believe.

1 Like

It is a shortcut reference link. You can think of all items in scope like [`item`] getting link definitions.

2 Likes

See here for the documentation of this feature: Linking to items by name - The rustdoc book

It contrasts with “normal Markdown” there, too:

Unlike normal Markdown, [bar][Bar] syntax is also supported without needing a [Bar]: ... reference link.

I see it as it automatically inserting missing links for items in scope when necessary, so it behaves a lot as if there were implicit [Bar]: /link/to/Bar-docs or [`item`]: /link/to/item-docs declarations (or rather, officially, "link reference definitions", I suppose) added.

Regarding back-ticks, they aren’t a necessary component of this feature, but they are permitted, and often you want the monospace code-style rendering:

Backticks around the link will be stripped, so [`Option`] will correctly link to Option.

5 Likes

Finally, an advanced albeit interesting feature is that they can be used inside manual <code>…</code> blocks; that is:

[`SomeItem`]

is equivalent to:

<code>[SomeItem]</code>

And you can imagine how the latter can be extended, which is especially handy for generic traits or types:

<code>#\[[your_attr]\]</code>
<code>[Vec]<T></code>

Note, however, how you'll need to escape typical html-sensitive stuff, such as &, < and >, or even '; but at least a backquote \ suffices to escape them (EDIT: it looks like escaping < and > is not always necessary :thinking:)

3 Likes

Interesting... So that means that Rust simply looks for these brackets combinations in the source comment before passing it to a Markdown parser and, like, if the item doesn't exist, it either fails or leaves the input as is? Or indeed it uses a Markdown parser passing a processor for these shortcuts?

In overly reductive short: I believe (though did not verify that) it is using the markdown parser to identify the anchorless markdown links. However, the interaction between markdown and inline HTML is a complex pit of annoying edge cases. Every "good" markdown parser needs to understand enough of HTML to be able to guess when HTML tags are block-level or inline to determine if markdown syntax processing should get suppressed or not.

<code> is considered an inline tag, so (apparently) doesn't disable markdown processing inside of it. (And since generally markdown uses ` for code markup, this is both useful and not problematic.[1])


  1. And markdown also supports escaping backticks within inline code, e.g. as I've done there, authoring the markdown as `` ` ``. It gets unwieldy quick if you need double backticks (or more) inline, though, since it's just "use enough backticks that it doesn't occur in the inline code" (e.g. to get that inline code block, I've written space-separated groups of 3 2 1 2 3 backticks). ↩︎

1 Like

5 Likes