Allow way to get merged doctests while developing on latest when MSRV doesn't support 2024 Edition

[epage]

Many of the example packages used when showing the value of merged doctests run on an old MSRV and can't benefit from it. I'd go so far as to presume that the packages with the most doctests are likely the most mature and therefore have the most demand for a low MSRV. This prevents those that need it the most to use this feature.

jiff works around this by having CI inject an edition = "2024" but that doesn't work for local development without special knowledge to do so and the risk of merging it.

It would be helpful to have a way to explicitly opt-in to merged doctests without bumping MSRV.

[epage]

We discussed this at the All Hands. Because rustdoc ignores unknown attributes in doctest infostrings, we can insta-stabilize a change in the attributes that would allow a user to opt-in without bumping MSRV.

Because of integration with other tools that don't support key-value pairs without other work, like rustdoc does for CSS, this will need to be its own attribute, rather than standalone_crate=false. We discussed the name merged_crate.

In the doctest-json output, we should probably specify this as a separate entry.

I propose that this new attribute be "force merge" while the current behavior is "auto" where it will attempt a merge and, on error, fallback to standalone.

We may want an allow-by-default lint to help find doctests without either standalone_crate or merged_crate.

The main question left is what to do when you specify both standalone_crate and merged_crate. Options include

• Hard error
• Deny by default
• Warn by default

If one of the last two are chosen, then we need to decide what behavior this entails which can include

• auto
• standalone, because it was stabilized first
• standalone, because it is the safer option

[epage]

When mixing both attributes, the consensus is to deny-by-default to reduce breakage.

When we allow unknown attributes, any time we add a new one that constricts behavior, we could break someone. The specifity and length of the name dramatically reduces the chance of doing so. If one solution requires a local edit, then another solution requiring it doesn't seem like a big deal. For me, the main concern is whether the local edit is required by dependents.

So from that context,

• A hard error or deny-by-default both include the solution of changing the infostring. The latter could also be done by changing the lint level.
• I always forget the details of cap-lints but I think both of these would affect dependents if the warning is emitted during any docs build. If we could limit it to only doctest build, then that would work.

So I propose

• If we are ok with the diagnostic triggering during doctest build, then we might as well hard error
• If we want this to run during any documentation build, I would either hard error or warn.

If we warn, then I propose we default to standalone behavior as that is the safest option.

[jyn514]

I would love to have this as a CLI flag that applies to the whole crate (an unstable one is fine).

Because rustdoc ignores unknown attributes in doctest infostrings, we can insta-stabilize a change in the attributes that would allow a user to opt-in without bumping MSRV.

I'm not sure I follow, are you talking about codeblocks in markdown? That means you're intending a per-test opt-in, rather than per-crate?

[epage]

I'm not sure I follow, are you talking about codeblocks in markdown? That means you're intending a per-test opt-in, rather than per-crate?

Yes, a per test basis like the other behavior modifying infostring attributes for doctests.