ensure all terms in glossary also exist in main text by tshepang · Pull Request #689 · rust-lang/fls

tshepang · 2026-04-04T22:22:32Z

It will be more easy to review commits individually.

This is part of #680, and a number of fixes and improvements (I think) were made along the way.

The one commit am not so sure of is bd6ab3f... I can imagine doing it differently, but am not sure it that will make the diff smaller.

rustbot · 2026-04-10T18:11:08Z

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

PLeVasseur

Hey @tshepang -- thanks so much for taking the time to do this work!

I think what I found was a mix of real issues and various levels of nits.

Happy to hear your thoughts.

View changes since this review

PLeVasseur · 2026-04-19T01:06:59Z

-A :dt:`syntactic category` is a nonterminal in the Backus-Naur Form grammar
-definition of the Rust programming language.
-
 tail expression


If these terms are meant to move out of the glossary, they seem to want chapter homes in src/general.rst, not deletion. construct fits best in General > Structure near src/general.rst:147-160, where that section repeatedly explains what each chapter says about a construct, while syntactic category fits best in General > Method of Description and Syntax Notation near src/general.rst:252-263, right where PascalCase grammar names are introduced. Could we move them there rather than deleting syntactic category outright? Failing that, I think we need to keep syntactic category for now, since construct at src/glossary.rst:944-945 still depends on it.

nice that you caught this because it was not supposed to be deleted (and I found a few other cases affected in a similar way)

construct in General is just used as an example... made separate structure demo from parent chapter #699 to make it more clear

PLeVasseur · 2026-04-19T01:06:59Z

-An :dt:`unnamed lifetime` is a :t:`lifetime` declared with character 0x5F (low
-line).
-
 unqualified path expression


elided lifetime at src/glossary.rst:1255-1256 still depends on unnamed lifetime to distinguish the '_ case from implicit omission, so removing unnamed lifetime leaves that glossary term dangling. If the intent is to migrate this term out of the glossary, its natural chapter home seems to be src/types-and-traits.rst in Lifetime Elision, where the spec already says a lifetime may be elided implicitly or explicitly and that explicit elision is the '_ lifetime (src/types-and-traits.rst:3237-3244; see also the LifetimeIndication syntax at 2907-2910). Could we move unnamed lifetime there as a chapter-level :dt: definition instead of deleting it outright? Failing that, I think we need to keep the term for now, since elided lifetime still depends on it.

See da45bbd, which resulted from me noticing (thanks to you) there were duplicate terms... existence of "unnamed lifetime" is already covered by fls_5ZAQ9p7jQuc2

PLeVasseur · 2026-04-19T01:06:59Z

 :dp:`fls_hyi2jnp38v1n`
-A :t:`generic parameter` is said to constrain an :t:`implementation` if the
-:t:`generic parameter` appears at least once in one of the following:
+A :t:`generic parameter` is said to :dt:`constrain` an :t:`implementation` if it makes the applicability of the :t:`implementation` more narrow.


The old wording here, and the Rust Reference, made the bullet list the direct rule for when a generic parameter constrains an implementation. This rewrite replaces that with a broader gloss and moves the actual criterion into a separate sentence about when "a constraint happens", which makes the rule less explicit. Could we keep the direct formulation here, or otherwise say explicitly that a generic parameter constrains the implementation exactly when it appears in one of the following places? If so, src/glossary.rst:939 may need the same tightening, though that broader glossary phrasing predates this PR.

hm, am thinking this is fine as the new rule is still accurate, and that it is fine for rules to be further tightened with other rules

am happy to change this though if you feel strongly... I feel weakly, but I did this to avoid definitions being defined by lists, instead of being able to stand alone

"Constrain" is a very broad notion, so I do not think it should be made into a term. The former wording acts as an introduction to the various cases enumerated below.

PLeVasseur · 2026-04-19T01:06:59Z

 ~~~~~~~~~~~~~~~~

+:dp:`fls_BBz4Iy7AeaU4`
+:dt:`Call conformance` measures the compatibility between a set of :t:`[argument operand]s` and a set of :t:`[function parameter]s` or :t:`[field]s`.


This new copy fixes the old a set if typo, but the glossary copy at src/glossary.rst:683-685 still says a set if, so the two definitions now diverge. Since this PR is aligning glossary and main-text terminology, could we sync the glossary definition too?

https://github.com/rust-lang/fls/compare/da45bbd3662b66b6b587aa3f588888a51cf4b249..aa8a0676558a4b3f3bfbdd195e62ca2b4afd177b

PLeVasseur · 2026-04-19T01:06:59Z

+FLS maintenance
+---------------
+
+- Paragraphs added or changed to ensure all glossary terms are also found in the main text:


This maintenance summary feels stronger than the current state of the PR. The branch still leaves live references to removed glossary terms at src/glossary.rst:945, 1255, and 3537, so the claim here seems too strong as written. This block also does not appear to cover the full set of related edits: fls_rnty1c8l5495 (src/macros.rst:28) and fls_aie0tr62vhw5 (src/types-and-traits.rst:1767) are not listed here, and fls_kv533rntni1x (src/patterns.rst:91) is only mentioned earlier in the changelog. Could we narrow the wording here, or wait to add the stronger summary until those dangling references are resolved?

I would not want to PR to be accepted until the maintenace summary claim is reached

the example ids are mere wording fixes/adjustments and therefore do not need to be accounted for in the changelog

PLeVasseur · 2026-04-20T00:29:48Z

-
-A :dt:`crate root` is an entry point into a :t:`crate`.
-
 crate root module


This branch removes crate root but keeps crate root module as the surviving defined/main-text term (src/glossary.rst:1010-1014, src/program-structure-and-compilation.rst:207-215). I could only find one remaining crate root use, the wrapped reference at src/entities-and-resolution.rst:953-954 (:t:`crate\nroot```), while nearby and elsewhere the spec already uses `crate root module`. Could we rewrite that survivor to :t:`crate root module``` so the terminology is consistent with the retained chapter-defined term?

PLeVasseur · 2026-04-20T13:29:31Z

+  - :p:`fls_Odh6Z7ivD1U4`
+  - :p:`fls_FG0EmVgrDUDq`
+
+- Paragraphs changed to avoid referencing indirect terms:


This PR shows a potential process gap: unresolved :t: fallout can pass CI (for example src/glossary.rst:945, src/glossary.rst:1255, src/glossary.rst:3537, and wrapped ``:t:crate\nroot``` at src/entities-and-resolution.rst:953-954`). Since this tracking effort depends on moving terms into chapter `:dt:` definitions safely, we should have an automated guardrail. Could we track a dedicated lint or CI check that verifies every `:t:` resolves to a live `:dt:` definition, including wrapped forms, rather than relying on manual cleanup?

Details:

Missing :t: refs do not become Sphinx warnings in this repo.

In exts/ferrocene_spec/definitions/init.py:136-158, if a definition target is missing, the extension does this:

it does not log a warning

it does not create a broken link

it replaces the role with plain inline text and adds CSS class spec-missing-ref

For term refs specifically, exts/ferrocene_spec/definitions/terms.py:37-38 returns just nodes.Text(text).

The theme then only colors that text as an error in HTML: themes/fls/static/fls.css:761-763.

PLeVasseur · 2026-04-20T13:33:46Z

+token
+^^^^^

-A :dt:`thin pointer type` is an :t:`indirection type` that refers to a


This seems workable as-is, but it does leave the pointer terminology a little asymmetric. This PR folds thin pointer type into the value-level thin pointer (src/types-and-traits.rst:1513), while fat pointer type remains the surviving type-level term (src/types-and-traits.rst:1410; glossary copy at src/glossary.rst:1458-1461). If that asymmetry is intentional, no change is needed; otherwise, would we want to either keep both sides type-level or add a lightweight value-level fat pointer companion beside fat pointer type?

PLeVasseur · 2026-04-20T13:33:46Z

 ^^^^^^^^^^^^

-A :dt:`thin pointer` is a :t:`value` of a :t:`thin pointer type`.
+A :dt:`thin pointer` is a :t:`value` of  an :t:`indirection type` that refers to a :t:`fixed sized type`.


Minor typo: of an has a doubled space here; the chapter copy at src/types-and-traits.rst:1513 has the same typo. Could we fix both copies?

PLeVasseur · 2026-04-20T16:47:50Z

-record struct type
-^^^^^^^^^^^^^^^^^^
-
-A :dt:`record struct type` is the :t:`type` of a :t:`record struct`.


record struct type seems to have a natural chapter home in src/types-and-traits.rst under Struct Types, immediately after the base struct type definition at src/types-and-traits.rst:766-768. That section already introduces RecordStructDeclaration / RecordStructFieldList syntax (src/types-and-traits.rst:738-750), and the next rules immediately start talking about record struct field (src/types-and-traits.rst:770-777). If the intent is to migrate glossary terms into chapters, could we move record struct and record struct type there together instead of deleting record struct type outright? Failing that, I think we need to keep record struct type for now, since record struct field at src/glossary.rst:3537 still depends on it.

… expression"

Also, replace duplicated terms regarding to lifetimes

kirtchev-adacore · 2026-04-23T12:10:35Z

 :dp:`fls_hyi2jnp38v1n`
-A :t:`generic parameter` is said to constrain an :t:`implementation` if the
-:t:`generic parameter` appears at least once in one of the following:
+A :t:`generic parameter` is said to :dt:`constrain` an :t:`implementation` if it makes the applicability of the :t:`implementation` more narrow.


"Constrain" is a very broad notion, so I do not think it should be made into a term. The former wording acts as an introduction to the various cases enumerated below.

kirtchev-adacore · 2026-04-23T12:13:12Z

 and the :t:`output register expression` shall have the same :t:`type`.

+:dp:`fls_FG0EmVgrDUDq`
+:dt:`NaN-boxing` is a technique for encoding :t:`[value]s` using the low order bits of the mantissa of a 64-bit IEEE floating-point ``NaN``.


In my opinion, NaN-boxing is an implementation details, and should not be mentioned in the FLS.

Numerical details are delegated to the corresponding primitive types, and those are currently outside the scope of the FLS.

kirtchev-adacore · 2026-04-23T12:19:08Z

+:dp:`fls_5SVthCNZBcVS`
+A :dt:`syntactic category` is a nonterminal in the Backus-Naur Form grammar definition of the Rust programming language.
+
+:dp:`fls_SonodAQVL5J4`
+A :dt:`construct` is a piece of program text that is an instance of a :t:`syntactic category`.
+


These terms have no business being defined in the section for comments. I think they should at the bottom of 1.1.4. Method of Description and Syntax Notation.

What do you think @PLeVasseur ? I was also considering a new section in 2. Lexical Elements, but we are now at a higher level of abstraction. The two rules relate to BNF.

View changes since the review

kirtchev-adacore · 2026-04-23T12:23:07Z

+:dp:`fls_Odh6Z7ivD1U4`
+A :dt:`unit enum variant` is an :t:`enum variant` without a :s:`RecordStructFieldList` or :s:`TupleStructFieldList`.
+


Do not simply append new rules to the end of a section. You should consider where they go within that section based on the flow of information being introduced.

For instance, this rule should go after 4.5.1:3 An enum variant... since it is closely related to enum variants, and introduces a new form of an enum variant. Placing it after a rule about exceeding the maximum value of a type is bizarre, as it has no relation to the immediately preceding rules.

View changes since the review

kirtchev-adacore · 2026-04-23T12:24:39Z

+:dp:`fls_9bp4cKSfW9A0`
+A :dt:`unit struct` is a :t:`struct` without a :s:`RecordStructFieldList` or a :s:`TupleStructFieldList`.
+


This rule should come after :dp:fls_mdejdc0nNgyO, since it is introducing yet another kind of struct.

View changes since the review

kirtchev-adacore · 2026-04-23T12:32:36Z

 The :t:`size` of a :t:`recursive type` shall be finite.

+:dp:`fls_twC8XhwbI60x`
+A :dt:`thin pointer` is a :t:`value` of  an :t:`indirection type` that refers to a :t:`fixed sized type`.


Section 4.7. Indirection Types should be given its own Legality Rules, and this rule should be relocated there.

On a side note, is "thin pointer" used anywhere else in the FLS?

tshepang added 4 commits April 4, 2026 23:12

ensure main text has all glossary entries

97a79ae

improve definition of token

3d392b5

stray

e7a3134

unwrap

3c69b77

kirtchev-adacore self-requested a review April 17, 2026 14:18

PLeVasseur requested changes Apr 20, 2026

View reviewed changes

tshepang force-pushed the tshepang/match-glossary branch from 51752ff to fac99b3 Compare April 23, 2026 09:17

tshepang added 9 commits April 23, 2026 12:22

match glossary definition with fixed one from main text

6eea056

remove glossary terms not referenced in main text

1cb541a

merge "thin pointer type" into definition of "thin pointer"

cac7144

remove undefined terms, "foo assignment", in favor of "foo assignment…

ce09e7d

… expression"

merge "field list" into definitions of where it is used

447a7d8

ensure main text has all glossary entries (part 2)

fb8add7

remove contorted singularization

99b2780

missed ids

9272157

ensure main text has all glossary entries (part 3)

aa8a067

Also, replace duplicated terms regarding to lifetimes

tshepang force-pushed the tshepang/match-glossary branch from da45bbd to aa8a067 Compare April 23, 2026 10:22

kirtchev-adacore requested changes Apr 23, 2026

View reviewed changes


		A :dt:`crate root` is an entry point into a :t:`crate`.

		crate root module

		:dp:`fls_Odh6Z7ivD1U4`
		A :dt:`unit enum variant` is an :t:`enum variant` without a :s:`RecordStructFieldList` or :s:`TupleStructFieldList`.

		:dp:`fls_9bp4cKSfW9A0`
		A :dt:`unit struct` is a :t:`struct` without a :s:`RecordStructFieldList` or a :s:`TupleStructFieldList`.

Conversation

tshepang commented Apr 4, 2026

Uh oh!

rustbot commented Apr 10, 2026

Uh oh!

PLeVasseur left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PLeVasseur left a comment •

edited by rustbot

Loading

kirtchev-adacore Apr 23, 2026 •

edited by rustbot

Loading

kirtchev-adacore Apr 23, 2026 •

edited by rustbot

Loading

kirtchev-adacore Apr 23, 2026 •

edited by rustbot

Loading