Add specific never search

[GuillaumeGomez]

Fixes #49529.

r? @QuietMisdreavus

[shepmaster]

r? @QuietMisdreavus

[novacrazy]

Would it not be better to add some kind of generic syntax alias system?

For example, while this may fix searching for !, many other things like ? and any operators (+, %, /, *, [/], etc.) still give weird results.

[GuillaumeGomez]

This is an excellent point! I'll update this PR with these new adds.

[novacrazy]

Maybe something like this?

query = (function() {
    switch(raw) {
        case '!': return "Never";
        case '?': return "try!";
        case '+': return "Add";
        case '-': return "Sub";
        case '%': return "Rem";
        case '[':
        case ']': return "Index";
        // and so forth
        default: return raw;
    }
})();

[kennytm]

[] can also refer to slices, and - could also mean the Neg trait. Could query support unioning results? 🤔

[GuillaumeGomez]

I think I'll need to introduce a new syntax. Something like 'vec|Neg' and then it'll look for the both. What do you think of it?

[novacrazy]

Perhaps a comma would work better? As if it’s a list of search terms rather than a full expression. That would leave | free for aliasing to BitOr as well.

[kennytm]

💡 Alternative: Allow items to register symbols as an alias index, like how the primitives are presented.

Rationale: Non-std docs don't care about ! being the never type. Modifying the *.js infects those non-std docs.

#[doc(primitive = "never")]
#[doc(alias = "!")]
/// blah
mod prim_never { }

#[doc(primitive = "slice")]
#[doc(alias = "[]")]
mod prim_slice { }

#[doc(alias = "-")]
pub trait Neg { }

#[doc(alias = "-")]
pub trait Sub { }

[novacrazy]

Is there a way to make a doc attribute like that require an unstable feature flag? That’s not really my area.

I feel like it could be abused in crates, yet it should be allowed in crates on the rare occasion users need to define their own lang items, like with no_core bare-metal projects.

Edit: Can no_core crates even build documentation?

[kennytm]

@novacrazy

Is there a way to make a doc attribute like that require an unstable feature flag?

Yes, that's how #[doc(cfg/masked/spotlight)]'s feature-gating works.

[GuillaumeGomez]

@kennytm: This is a brilliant idea. I'm just a bit afraid that people might misuse it though or that readers won't be aware of it, and therefore not use it... But this remains an excellent idea. I think I'll start implementing it.

[shepmaster]

that people might misuse it though

You could put restrictions that the "alias" has to be non-word characters to start with. This might mitigate overall abuse.

[GuillaumeGomez]

Indeed!

[QuietMisdreavus]

+1 for adding a general mechanism. Adding a feature gate to a doc-attribute parameter is easy. The compiler already whitelists the doc attribute as a whole, so adding a check for a specific parameter just involves knowing the right place to put it.

Edit: Can no_core crates even build documentation?

@novacrazy Yes - as long as the compiler can build it, so can rustdoc. For example, libcore is a #![no_core] crate, and its docs build fine.

[pietroalbini]

Blocked on #49966

[kennytm]

@pietroalbini My alternative in #49757 (comment) wouldn't need #49966, though if the alternative is chosen, this PR should be closed or entirely rewritten.

[bors]

☔ The latest upstream changes (presumably #50033) made this pull request unmergeable. Please resolve the merge conflicts.

[GuillaumeGomez]

@kennytm: Your doc alias can be the same for multiple types so it still strongly requires the multi-query feature.

[kennytm]

@GuillaumeGomez I don't think so, I expect there would be multiple dedicated entries named [] or - etc, and the search UI would be like:

[GuillaumeGomez]

Ok, here's all the implemented functionality. I finally went for last @kennytm's comment: no need for multiquery, I just add types at the beginning of the results and we're good!

cc @QuietMisdreavus

[kennytm]

We could delete this code now right? 😄

[GuillaumeGomez]

Oh damn! Completely forgot about it 😆

[GuillaumeGomez]

Updated.

[QuietMisdreavus]

Looks good! One round of requests from me:

• Can you open up a tracking issue for the new doc_alias feature and reference it in your feature gate?
• Could you write up some docs in src/doc/unstable-book/src/language-features/doc-alias.md talking about what the attribute does?
  • Optional: add a note in src/doc/rustdoc/src/unstable-features.md alongside the other doc attribute stuff linking to the Unstable Book page

[QuietMisdreavus]

Great, thanks so much! r=me pending travis.

[kennytm]

@bors r=QuietMisdreavus

[bors]

📌 Commit 1ed3e77 has been approved by QuietMisdreavus

[bors]

⌛ Testing commit 1ed3e77 with merge bbdd1cf...

[bors]

☀️ Test successful - status-appveyor, status-travis
Approved by: QuietMisdreavus
Pushing bbdd1cf to master...