Document 'sigils' in std docs?

documentation
14

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.

You might have a point that the Reference could be a better place of documenting the underlying constructs.

In that case I think:

  • the Keywords section from std should actually move / be merged with the reference
  • the Reference needs a simple "visual recognition guide" that is a mix of the current std Keywords and the proposed "Sigils" (one reason I want this is having the ability to look up a construct I saw in code which the current reference does not provide)
  • The std documentation should maybe have a "Keywords & Sigils" section at the end (replacing keywords) that just prominently links to that "visual recognition guide" to make sure there is an easy path of discoverability.

I could get used to both, std or reference. I just think wherever keywords go there should be a comparable "non-keyword construct" section with easy discoverability and mid-level explanation.

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

In my (naive) understanding < does not do anything interesting on its own (see below), and <T> is the canonical way to express a type parameter; so I would put it there. That page could be have a description of "generic type syntax".

What searches would we want to lead people to these pages? i.e., should https://doc.rust-lang.org/std/?search=<T> send me to a “generic functions syntax” page? What about searching fn foo<T>() -> T {} ?

I have not thought about searching.

For the other symbols present in fn foo<T>() -> T {} I would only document <T>.

Regarding the other tokens, fn is a keyword, and (), ->, {} are "not exciting enough", as they do not behave significantly differently than in other languages on this level. I would also not document < on its own (as a comparison operator), by the same logic.