Document 'sigils' in std docs?

[Ixrec]

@rbx

Out of curiosity, why are keywords then documented they way they are now?

I'm not on the docs team or anything so it's not like I can officially answer this, but I imagine it makes more sense for keywords because:

1. Whether something is or is not a "keyword" is pretty much an objective fact. "Sigil" is significantly fuzzier.
2. Keywords are much easier to search for than sigils, so the odds of someone ever looking for and then actually finding the docs for them is much higher
3. We're far more likely to use keywords than sigils for niche, special-purpose features where dedicated documentation makes sense (e.g. become for guaranteed TCO).
4. There are just more keywords than there are sigils, and that's likely to become more true in the future.
5. Sigils are also a lot broader and fuzzier in scope, so it's harder to tell what would even go on a sigil's doc page. For instance, the if keyword page obviously should say something about if expressions, and that's about it. The & sigil page should clearly mention references, but should it also talk about borrow checking? Move semantics? Deref coercion?

Obviously none of this is an argument that sigil documentation is a non-starter, just that keyword docs are a lot more straightforward and obviously useful.

@rbx

Sample use case: "I want to write a generic function and I know it was something with <T> ". The documentation there might then in bullet points list:

• that these get monomorphized or become template methods depending on impl or dyn
• you can’t use types but only traits for T k
• when T is Sized or not, and what that means
• that bounds can be specified with T : X , where
• …

What page would this be though? The < sigil page? The <T> page? Or a "generic functions syntax" page?

What searches would we want to lead people to these pages? i.e., should std - Rust send me to a "generic functions syntax" page? What about searching fn foo<T>() -> T {}?

I'm not necessarily opposed to any of these ideas, it's just very unclear to me what pages there would be, what would be on them, how users would find them, and what use cases it would actually solve, which to me is a strong sign that "sigils" might not be the right thing to focus on.

@rbx

Edit: Also, the name sigil might be misleading and I totally don’t mind changing it. What I just want is something more than keywords that explains the most common language constructs (expressed by non-keyword symbols) in a concise way.

And this is exactly the kind of thing I was really trying to get at. In other words, instead of going after individual "sigils" maybe we'd get far more benefit out of documenting larger syntactic constructs like "trait bounds syntax" or "generic functions syntax" or "closure syntax". Those are things I can actually imagine people searching for successfully and have relatively clear scope.

Which then gets us to questions like should the std docs be documenting syntax, or is that the Reference's job? This might also overlap with whatever the Grammar Working Group is doing.

Again, I'm not trying to argue against doing anything, but for being much clearer about what the goal is supposed to be. For instance, my first thought now is to let the Reference be in charge of exhaustively and comprehensively documenting the formal grammar, but to also add std docs pages for things like "generic function syntax" that links to the relevant part of the Reference, then walks through a few toy examples of the most interesting and useful parts of the syntax like a basic type parameter, then a trait bound, then an impl trait, etc, and finally ends on a bullet point list of links to further reading such as a chapter in The Book on HRTBs. That seems way more likely to be discoverable and useful for novices searching "how do I write generic functions in Rust?" than, say, a doc page for the < sigil.