Documentation interpolation

[clarfonthey]

You ever get so annoyed by something that you write up an RFC to fix it?

Basically expecting this to be completely ignored for one week minimum due to Rust Week, but this is something that always annoyed me and so I figured that I would try and take a stab at it.

Summary

Add the ability to use #{...} expressions in documentation comments for macro interpolation.

For example, #{$name} would be replaced with the result of stringify!($name) if used in documentation comments, and expressions like #{my_macro!($name)} also work.

Important

Since RFCs involve many conversations at once that can be difficult to follow, please use review comment threads on the text changes instead of direct comments on the RFC.

If you don't have a particular section of the RFC to comment on, you can click on the "Comment on this file" button on the top-right corner of the diff, to the right of the "Viewed" checkbox. This will create a separate thread even if others have commented on the file too.

Rendered

[tgross35]

Perhaps a prefixed foo( doc#{$bar} ) syntax would be a good option to (1) further reduce conflict chances, and (2) give a cue that it's documentation-related rather than something in the code.

View changes since the review

[clarfonthey]

Honestly, changing the syntax to #{...}, the syntax does kind of write itself…

Will have to ponder.

[tgross35]

As an alternative solution to solve the same problem, things would probably be less terrible if we had an inline concat syntax. Something like:

#[doc = concat2!("assert_eq!(({$SelfT}::MIN + 2).checked_sub(1), Some({$SelfT}), "::MIN + 1));")]
#[doc = concat2!("assert_eq!(({$SelfT}::MIN + 2).checked_sub(3), None);")]

Not that we couldn't have both :)

View changes since the review

[clarfonthey]

I actually do like this idea a lot, although I would like to still keep the doc comment syntax since I think that the misalignment between /// and #[doc = ...] really makes reading things harder.

General string interpolation for macros itself is something that would be worth exploring as worthwhile in its own right, and probably doesn't need to replicate the entire format_args! machinery to be useful.

[lebensterben]

even though I understand the intention of this PR, it still makes me feel like this new expression isn't just rustdoc only, but changing the transcribing of macro by example.

also, how would repetition be dealt with?

View changes since the review

[clarfonthey]

This is making me think that this could probably genuinely use a few more examples.

Repetition, to me, would be done exactly how it's done any other way:

$(
    /// ${$thing}.
    struct $thing;
)

Would work, if $thing is repeating at its current depth.

[lebensterben]

I'd like to propose an alternative to this new syntax.

Let's support fenced_code_attributes extension of Pandoc's Markdown

For code blocks, it would be one of the following equivalent:

```{.rust macro_interpolation=true}
assert_eq!(($SelfT::MIN + 2).checked_sub(3), None);
```

```rust {macro_interpolation=true}
assert_eq!(($SelfT::MIN + 2).checked_sub(3), None);
```

```{macro_interpolation=true}
assert_eq!(($SelfT::MIN + 2).checked_sub(3), None);
```

Here .rust is a class, and macro_interpolation=true is an attribute. (We may also allow named code block by using #id.)

The first syntax is the full syntax. The second one is a shorthand for code blocks in Pandoc's Markdown. And the third one is RUSTDOC's shorthand for defaulting code block language to Rust.

Similarly, for inline code, we can allow inline_code_attributes:

`assert_eq!(($SelfT::MIN + 2).checked_sub(3), None);`{.rust macro_interpolation=true}

(optionally allow .rust be omitted)

---

Now suppose for some reason, within a code block we have some items that start with $ sigil and we don't want it to be interpolated, but others do. We should introduce a way to escape interpolation, for example by escaping $.

---

It's worth noting that allowing macro interpolation everywhere could be dangerous. At least in short term I think we should only allow std and rust internal macros to be interpolated.

View changes since this review