Explain how to name rule identifiers

[chorman0773]

This adds guidelines for using spec identifier syntax in the reference.

It is also intended to aid review in the PRs for adding spec identifier syntax.

[traviscross]

@ehuss and I talked about this part. We're a but uncertain about the strategy here. It feels like there are going to be a ton of restriction-this and constraint-that rules, and we're not sure that it carries its weight.

We're also probably unconvinced on this means of separating syntactic and type checking requirements. I.e., it doesn't immediately speak to us that "restriction" would refer to parsing and "constraint" would refer to type checking and that these should be separated in this manner.

This probably also applies to some of the others, such as "preconditions".

[chorman0773]

I haven't seen ambiguous keyword rules too often in my work, though that might change once I start my second pass.

As for the specific terms, I'd like to discuss that tomorrow at the T-spec meeting.

[traviscross]

I'm not sure this is true everywhere. Plural often makes sense. I'd expect chapter titles like "Items" (rather than "Item") or "Lints" (rather than "Lint"), and I'd expect the rule names to follow suit here.

Often, what's going to come up, as it did with the diagnostic namespace, is not the difference between plural and singular, but the difference between nouns and adjectives. As a noun, it makes sense for the chapter title (and rules that follow that) to be "Diagnostics", but when used with "diagnostic namespace", it's an adjective, and so it doesn't have the "s".

[chorman0773]

item.fn

[traviscross]

Can we think of any examples of where this would come up?

[chorman0773]

AssertUnwindSafe is probably close (assert-unwind-safe if we ever refer to it in the reference). I can't think of any specific examples, but that doesn't mean it won't happen (especially if we expand the list of keywords).

[traviscross]

In discussion we were a bit unclear about the distinction being drawn here. Perhaps more examples would help.

[chorman0773]

I actually did this a couple times working on #1618. r[type.trait-object.syntax-edition2021] - it refers to Edition 2021 and modifies the syntax rule accordingly, so we use a suffix here. r[type.text.char-precondition] is a precondition that applies to char, rather than modifying a general precondition because of the use of char.

As another example, r[items.fn.params.self-constraint], is talking about the functions that can use a self param... which probably should be a suffix here as well, thinking about it. self-constraint probably should be for talking about what types a self param could have.

[traviscross]

On the lang-docs call, we had a long discussion about this. The general thrust is that we'd like in general to be descriptive rather than prescriptive and to follow patterns that emerge from a recurring need in the Reference.

To that end, we want to remove the specific keywords noted in the document, other than "intro", "syntax", and "namespace".

We want to remove the prescriptive note about singular versus plural. And let's remove this rule:

• Whenever possible, don't use a name that conflicts with one of the above keywords, even if this violates the first bullet.

Let's remove item 6 entirely also for the same reason.

And then, for this rule:

2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break

We didn't want to use hard line breaks for this. Instead, we're interested in moving all of the expository material into delimited notes sections (this applies also to rule 3).

[chorman0773]

Instead, we're interested in moving all of the expository material into delimited notes sections (this applies also to rule 3).

That was my thought as well, but that's a later pass to be honest. I'd rather have rules that keep things consistent now.

• Update: I note in the recent commit that such content should prefer being put into an admonition block (either [!NOTE] or something more specific like [!WARNING] or [!VERSION-DIFFERENCES])

[ehuss]

Thanks! I'm going to go ahead and approve, since I think we have agreement on what I've edited, and I don't want to block progress over specific points we haven't agreed on. Specifically:

• Version history: I don't think we've made an agreement if or how we're going to be documenting any historical information.
• Singular forms: I think we are using plurals almost all over (the existing rule PRs, section headings, etc.). There may be some subtle details about what guidance we want to give here, but I don't know if we can hammer them out in a very short term. For now, I think the identifiers should usually be plural to match the style in the section headers, and we can figure out what kind of refinement we want to give on that guidance in a followup. For example, we have some abbreviated or shortened forms that aren't plural, which seem fine to me. There are other factors, such as whether or not something is categorical, an initialism, an adjective, etc.