rustdoc standalone doctest attribute is confusing, taking up a potentially useful name

[epage]

#126245 merged support in Edition 2024 for consolidating doctests into as few binaries as possible, with an opt-out of a standalone attribute.

/// ```rust,standalone
/// let total = add(1, 3);
/// ```
fn add(x: i32, y: i32) -> i32 {
    x + y
}

In reading the code, without looking at the docs, the name's meaning is unclear. It wasn't until I saw a comment on reddit that I understood this to only mean "standalone binary" and not also "standalone process". It came up because someone else was confused on what was happening (reddit).

As shown by the confusion, there are other potential uses for this name and I am interested in exploring those (rust-lang/testing-devex-team#5), so this takes away a potential name for a workflow that could be a lot more common than the current meaning of standalone. The fact that standalone only has a couple of uses within this repo suggests its highly specialized and shouldn't be "squatting" on a generic name.

[epage]

For suggested names, I feel like crate works well as in "build this as its own crate"

I also think we could generalize standalone as a key-value pair (though this would likely be a first so that would raise its own questions) with a potential default. So this could be standalone-crate.

In discussing this with @GuillaumeGomez , the name not-merged also came up. I tend to prefer to describe things by what they are, rather than what they aren't, and merged doesn't say in what way things are merged. However, its an odd enough name that I'm ok with it for how specialized the use of this attribute is expected to be.

[GuillaumeGomez]

In the discussion, I pointed out that crate would be terrible for searchability, so I don't think it's a good candidate. I'm personally fine with standalone as it describes exactly what this doctest is, but I'm strongly biased and if people are asking what it does, then it might be not the best for the job. standalone-crate could be a good alternative too.

[BurntSushi]

I like crate the best personally. I like standalone-crate more than standalone. The problem with standalone is that it's somewhat ambiguous what it's referring to and it could legitimately be one of at least a couple different things I think.

[epilys]

A verb-object form (or a full-sentence form to be more accurate) could make the meaning clearer, for example compile-as-standalone-crate or even more verbose compile-this-test-as-standalone-crate or whatever other terminology is found appropriate. It's uglier but has the positive that it depends less on cryptic names and be more searchable due to more search synonyms for verbs, objects etc. This approach also depends less on the cultural background of the reader and their knowledge of English.

[GuillaumeGomez]

I like this approach. 👍

[epage]

compile-as-standalone-crate

If this were a more common attribute, I would be against such a long descriptive name. With it being for such a specialized set of use cases, I am not against it

compile-this-test-as-standalone-crate

I feel like "this test" is implied by what you are applying it to.

[epage]

One advantage of a key-value approach is we could allow people to opt-in to the feature early, reducing the need for MSRV bumps.

One level of reducing MSRV bumps is if the attribute is feature gated, erroring if not enabled, and then stabilized before Edition 2024. Even better is if we could ignore if its not enabled and then any MSRV would be compatible with this. In Cargo, we've been applying this model to reduce MSRV bumps where possible, mainly where there isn't a meaningful semantic difference to lose the functionality when on older versions.

[GuillaumeGomez]

You mean people would need to add the attribute on all doctests? Doesn't sound like a good idea to me. ^^'

[epage]

Only if they care enough about MSRV and the performance gains to not wait until 2024 Edition.

[GuillaumeGomez]

They can enable it in the CI and/or locally if they really can't wait. :)

[epage]

For me, this does not cross the threshold to be worth running nightly locally or for production tests as the bar to using nightly is high. I run nightly as a canary in CI to identify problems with my project or rustc early.