Repository navigation
rustdoc standalone doctest attribute is confusing, taking up a potentially useful name #129098
Description
#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.
Activity
epage commentedon Aug 14, 2024
For suggested names, I feel like
crateworks well as in "build this as its own crate"I also think we could generalize
standaloneas 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 bestandalone-crate.In discussing this with @GuillaumeGomez , the name
not-mergedalso 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.[-]rustdoc `standlone` doctest attribute is confusing, taking up a potentially useful name[/-][+]rustdoc `standalone` doctest attribute is confusing, taking up a potentially useful name[/+]GuillaumeGomez commentedon Aug 14, 2024
In the discussion, I pointed out that
cratewould be terrible for searchability, so I don't think it's a good candidate. I'm personally fine withstandaloneas 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-cratecould be a good alternative too.BurntSushi commentedon Aug 14, 2024
I like
cratethe best personally. I likestandalone-cratemore thanstandalone. The problem withstandaloneis 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 commentedon Aug 14, 2024
A verb-object form (or a full-sentence form to be more accurate) could make the meaning clearer, for example
compile-as-standalone-crateor even more verbosecompile-this-test-as-standalone-crateor 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 commentedon Aug 14, 2024
I like this approach. 👍
epage commentedon Aug 14, 2024
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
I feel like "this test" is implied by what you are applying it to.
epage commentedon Aug 14, 2024
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 commentedon Aug 14, 2024
You mean people would need to add the attribute on all doctests? Doesn't sound like a good idea to me. ^^'
epage commentedon Aug 14, 2024
Only if they care enough about MSRV and the performance gains to not wait until 2024 Edition.
GuillaumeGomez commentedon Aug 14, 2024
They can enable it in the CI and/or locally if they really can't wait. :)
epage commentedon Aug 14, 2024
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.
GuillaumeGomez commentedon Oct 1, 2024
It was renamed into
standalone_cratein #130931. Closing then.