rustdoc: Add [arg@name] intra-doc syntax for referencing function arguments

[nik-rev]

This PR adds a feature that allows referencing function arguments using the intra-doc syntax [arg@name].

Example

#![feature(intra_doc_arg)]

/// Apply a blur to an image of known [`arg@width`] and [`arg@height`],
/// where the raw image data resides in [`arg@img_data`]
/// in a row-major fashion.
fn blur(image_data: &mut [f32], width: u32, height: u32) {}

You may not be able to tell at a first glance, but the above example actually contains a typo. The img_data argument does not exist; instead, the function author meant to refer to the image_data argument.

Thankfully, because they explicitly referred to the argument with the intra-doc syntax [`arg@img_data`], rustdoc will emit an error for the above example:

error: argument `img_data` does not exist
  --> src/main.rs:27:16
   |
27 |     /// where the raw image data resides in [`arg@img_data`]
   |                                              ^^^^^^^^^^^^^^

Impact on generated HTML

In terms of the generated documentation, arg@ intra-doc "links" don't impact the HTML output at all. The links are stripped completely, and they are rendered equivalently to the following documentation:

/// Apply a blur to an image of known `width` and `height`,
/// where the raw image data resides in `image_data`
/// in a row-major fashion.

Exciting possibilities

if rustdoc gains an official syntax for referring to function arguments, rust-analyzer could also implement that - so you could rename your function's arguments and they would automatically be renamed in the documentation, for example.

Notes

Using the arg@ prefix is required. But if we are happy with it being inferred, I can make that happen.

Relevant issue: #57525

Implementation

1. PageId (the field that says "where is this this item's documentation") is now Option<DefId> instead of DefId, because intra-doc argument references do not refer to any particular item (function arguments are not real items)
2. Because of that, RenderedLink's href field is now Option<String> instead of String. When it is None, no link is generated in the HTML at all.
3. When it comes to modifying the markdown Events, the Event::Start(Link) is replaced with an empty text, and Event::End(Link) is also. So there is no link in the output.

---

Zulip discussion: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/Allow.20referencing.20function.20arguments.20in.20function.20docs.3F/with/577839079

[rustbot]

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: rustdoc
• rustdoc expanded to 9 candidates
• Random selection from GuillaumeGomez, camelid, fmease, lolbinarycat, notriddle

[GuillaumeGomez]

Mostly for me: the feature as of now checks if an argument exists and if so, replace the intra-doc link with the argument name, allowing to check that the docs are up to date. Not sure if it's worth generating IDs for all function arguments as it would increase quite a lot the HTML size. Maybe we could only generate IDs for arguments which are pointed by arg@? Anyway, can be discussed later on. Checking code now. :)

[nik-rev]

Considering what @kpreid said on zulip in (#t-rustdoc > Allow referencing function arguments in function docs? @ 💬):

I worry that always having arg@ significantly reduces readability of the doc as plain comments, and people might refrain from using the feature at all as a result. (But that could be changed compatibly later, since arg@ wouldn't mean anything else.

I agree with this quite a lot, so I have pushed a new commit (edit: reverted, but can bring back if needed) that adds implicit function argument support. I will squash that if this PR gets merged, but also keeping it as a separate commit so it can be easily reverted if needed.

[GuillaumeGomez]

I commented here why I don't think we should put the function arguments at the same level.

[nik-rev]

All unrelated code changes have been removed