docs(glossary): phase 1 main text coverage

exts/ferrocene_spec_lints/__init__.py

@@ -3,12 +3,13 @@
 
 import sphinx
 import typing
-from . import alphabetical_section_titles, require_paragraph_ids
+from . import alphabetical_section_titles, glossary_migration, require_paragraph_ids
 
 
 def run_lints(app, env):
     alphabetical_section_titles.check(app, raise_error)
     require_paragraph_ids.check(app, raise_error)
+    glossary_migration.check(app, raise_error)
 
 
 def raise_error(message, *, location=None):
@@ -21,6 +22,10 @@ def setup(app):
 
     app.add_config_value("lint_alphabetical_section_titles", [], "", typing.List[str])
     app.add_config_value("lint_no_paragraph_ids", [], "", typing.List[str])
+    app.add_config_value("lint_glossary_migration_phase", 0, "", int)
+    app.add_config_value("lint_glossary_migration_strict", False, "", bool)
+    app.add_config_value("lint_glossary_migration_report", "", "", str)
+    app.add_config_value("lint_glossary_migration_report_root", "", "", str)
 
     return {
         "version": "0",

exts/ferrocene_spec_lints/glossary_migration.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# SPDX-FileCopyrightText: The Ferrocene Developers
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+GLOSSARY_DOC = "glossary.rst"
+DT_ROLE_RE = re.compile(r":dt:`")
+
+
+def find_glossary_dt_lines(root: Path):
+    glossary = root / "src" / GLOSSARY_DOC
+    if not glossary.is_file():
+        return []
+
+    violations = []
+    lines = glossary.read_text(encoding="utf-8").splitlines()
+    for index, line in enumerate(lines, start=1):
+        if DT_ROLE_RE.search(line):
+            violations.append({"file": glossary, "line": index, "text": line.rstrip()})
+    return violations
+
+
+def check(app, raise_error):
+    phase = app.config.lint_glossary_migration_phase
+    strict = app.config.lint_glossary_migration_strict
+    if phase <= 0 or not strict:
+        return
+
+    root = Path(app.confdir).resolve().parent
+
+    if phase >= 3:
+        for violation in find_glossary_dt_lines(root):
+            location = f"{violation['file']}:{violation['line']}"
+            raise_error(f":dt: role remains in glossary source at {location}")

src/associated-items.rst

@@ -25,20 +25,28 @@ Associated Items
 .. rubric:: Legality Rules
 
 :dp:`fls_ckzd25qd213t`
-An :t:`associated item` is an :t:`item` that appears within an
+An :dt:`associated item` is an :t:`item` that appears within an
 :t:`implementation` or a :t:`trait`.
 
-:dp:`fls_5y6ae0xqux57`
-An :t:`associated constant` is a :t:`constant` that appears as an
+:dp:`fls_8cz4rdrklaj4`
+An :dt:`associated type` is a :t:`type alias` that appears as an
 :t:`associated item`.
 
-:dp:`fls_lj7492aq7fzo`
-An :t:`associated function` is a :t:`function` that appears as an
+:dp:`fls_wb049assocfn`
+An :dt:`associated function` is a :t:`function` that appears as an
 :t:`associated item`.
 
-:dp:`fls_8cz4rdrklaj4`
-An :t:`associated type` is a :t:`type alias` that appears as an
-:t:`associated item`.
+:dp:`fls_nNisRZ6p4T6u`
+An :dt:`incomplete associated constant` is an :t:`associated constant` without
+a :t:`constant initializer`.
+
+:dp:`fls_nMEacKMoaVn0`
+An :dt:`incomplete associated function` is an :t:`associated function` without
+a :t:`function body`.
+
+:dp:`fls_FJEqMV7Qt6ZJ`
+An :dt:`incomplete associated type` is an :t:`associated type` without an
+:t:`initialization type`.
 
 :dp:`fls_w8nu8suy7t5`
 An :t:`associated type` shall not be used in the :t:`path expression` of a
@@ -49,7 +57,7 @@ An :t:`associated type` with a :s:`TypeBoundList` shall appear only as an
 :t:`associated trait type`.
 
 :dp:`fls_PeD0DzjK57be`
-A :t:`generic associated type` is an :t:`associated type` with
+A :dt:`generic associated type` is an :t:`associated type` with
 :t:`[generic parameter]s`.
 
 :dp:`fls_3foYUch29ZtF`
@@ -69,42 +77,38 @@ or :c:`Self` and ``'lifetime`` is the :t:`lifetime parameter`, when
 * :dp:`fls_AtItgS1UvwiX`
   The intersection of all such uses is not empty.
 
-:dp:`fls_l3iwn56n1uz8`
-An :t:`associated implementation constant` is an :t:`associated constant` that
-appears within an :t:`implementation`.
-
 :dp:`fls_4ftfefcotb4g`
 An :t:`associated implementation constant` shall have a :t:`constant
 initializer`.
 
 :dp:`fls_qb5qpfe0uwk`
-An :t:`associated implementation function` is an :t:`associated function` that
+An :dt:`associated implementation function` is an :t:`associated function` that
 appears within an :t:`implementation`.
 
 :dp:`fls_1zlkeb6fz10j`
 An :t:`associated implementation function` shall have a :t:`function body`.
 
 :dp:`fls_tw8u0cc5867l`
-An :t:`associated implementation type` is an :t:`associated type` that appears
+An :dt:`associated implementation type` is an :t:`associated type` that appears
 within an :t:`implementation`.
 
 :dp:`fls_bx7931x4155h`
 An :t:`associated implementation type` shall have an :t:`initialization type`.
 
 :dp:`fls_bnTcCbDvdp94`
-An :t:`associated trait item` is an :t:`associated item` that appears
+An :dt:`associated trait item` is an :t:`associated item` that appears
 within a :t:`trait`.
 
 :dp:`fls_N3cdn4lCZ2Bf`
-An :t:`associated trait implementation item` is an :t:`associated item` that
+An :dt:`associated trait implementation item` is an :t:`associated item` that
 appears within a :t:`trait implementation`.
 
 :dp:`fls_x564isbhobym`
 An :t:`associated trait constant` is an :t:`associated constant` that appears
 within a :t:`trait`.
 
 :dp:`fls_b6nns7oqvdpm`
-An :t:`associated trait function` is an :t:`associated function` that appears
+An :dt:`associated trait function` is an :t:`associated function` that appears
 within a :t:`trait`.
 
 :dp:`fls_2TRwCz38kuRz`
@@ -116,7 +120,7 @@ Every occurrence of an :t:`impl trait type` in the :t:`return type` of an
 anonymous :t:`associated trait type` of the :t:`implemented trait`.
 
 :dp:`fls_yyhebj4qyk34`
-An :t:`associated trait type` is an :t:`associated type` that appears within
+An :dt:`associated trait type` is an :t:`associated type` that appears within
 a :t:`trait`.
 
 :dp:`fls_kl9p3ycl5mzf`
@@ -145,7 +149,7 @@ is equivalent to a :t:`where clause` of the following form:
    	}
 
 :dp:`fls_amWtS80fPtza`
-An :t:`associated trait implementation function` is an :t:`associated function`
+An :dt:`associated trait implementation function` is an :t:`associated function`
 that appears within a :t:`trait implementation`.
 
 :dp:`fls_Cu8FWrisrqz1`

src/attributes.rst

@@ -48,15 +48,15 @@ An :t:`attribute` is a general, free-form metadatum that is interpreted based on
 its :t:`name`, convention, language, and tool.
 
 :dp:`fls_yd0ehw5csaur`
-An :t:`inner attribute` is an :t:`attribute` that applies to an enclosing
+An :dt:`inner attribute` is an :t:`attribute` that applies to an enclosing
 :t:`item`.
 
 :dp:`fls_8o6vmzbw1b1j`
-An :t:`outer attribute` is an :t:`attribute` that applies to a subsequent
+An :dt:`outer attribute` is an :t:`attribute` that applies to a subsequent
 :t:`item`.
 
 :dp:`fls_9TMRVlQwAdTB`
-An :t:`attribute content` is a :t:`construct` that provides the content of
+An :dt:`attribute content` is a :t:`construct` that provides the content of
 an :t:`attribute`.
 
 .. rubric:: Examples
@@ -78,11 +78,11 @@ Attribute Properties
 .. rubric:: Legality Rules
 
 :dp:`fls_p4potvq7x532`
-An :t:`active attribute` is an :t:`attribute` that is removed from the :t:`item`
+An :dt:`active attribute` is an :t:`attribute` that is removed from the :t:`item`
 it decorates.
 
 :dp:`fls_xk7lb2g02sy7`
-An :t:`inert attribute` is an :t:`attribute` that remains with the :t:`item`
+An :dt:`inert attribute` is an :t:`attribute` that remains with the :t:`item`
 it decorates.
 
 :dp:`fls_q8wl7pidx2za`
@@ -166,7 +166,7 @@ Built-in Attributes
 .. rubric:: Legality Rules
 
 :dp:`fls_92tqo8uas8kd`
-A :t:`built-in attribute` is a language-defined :t:`attribute`.
+A :dt:`built-in attribute` is a language-defined :t:`attribute`.
 
 :dp:`fls_bxucstrfcco8`
 The following :t:`[built-in attribute]s` are :dt:`[code generation attribute]s`:
@@ -406,6 +406,8 @@ Attribute ``inline``
 
 :dp:`fls_s7bf7tf9206d`
 :t:`Attribute` :dc:`inline` marks its related :t:`function` as :dt:`inlined`.
+
+:dp:`fls_WKfvccIyiUsm`
 The process of replacing a :t:`call expression` to an :t:`inlined` :t:`function`
 with the :t:`function body` is referred to as :dt:`inlining`.
 
@@ -923,14 +925,14 @@ Attribute ``cfg``
 .. rubric:: Legality Rules
 
 :dp:`fls_xrjp7xw9jutz`
-:t:`Attribute` :dc:`cfg` enables :t:`conditional compilation`.
+:dt:`Attribute` :dc:`cfg` enables :dt:`conditional compilation`.
 
 :dp:`fls_l96kyix5xsof`
-A :t:`configuration predicate` is a :t:`construct` that evaluates statically
+A :dt:`configuration predicate` is a :t:`construct` that evaluates statically
 to either ``true`` or ``false``, and controls :t:`conditional compilation`.
 
 :dp:`fls_y1MUhnKCxK6T`
-An :t:`all configuration predicate` is a :t:`configuration predicate` that
+An :dt:`all configuration predicate` is a :t:`configuration predicate` that
 models existential quantifier ALL.
 
 :dp:`fls_tncxxsyutppf`
@@ -939,15 +941,15 @@ all nested configuration predicates evaluate to ``true``, or there are no nested
 configuration predicates.
 
 :dp:`fls_Rp73YEE3aFdI`
-An :t:`any configuration predicate` is a :t:`configuration predicate` that
+An :dt:`any configuration predicate` is a :t:`configuration predicate` that
 models existential quantifier ANY.
 
 :dp:`fls_m0zxktz168e0`
 An :t:`any configuration predicate` evaluates statically to ``true`` when any
 nested configuration predicate evaluates to ``true``.
 
 :dp:`fls_XsxeOd32JI8x`
-A :t:`not configuration predicate` is a :t:`configuration predicate` that
+A :dt:`not configuration predicate` is a :t:`configuration predicate` that
 negates the Boolean :t:`value` of its nested :t:`configuration predicate`.
 
 :dp:`fls_tvsadfy9uibu`
@@ -1486,11 +1488,10 @@ or :t:`static`.
 be publicly exported from the produced library or object file.
 
 :dp:`fls_VKuSiswPMll7`
-An :t:`exported function` is a :t:`function` subject to :t:`attribute`
-:c:`no_mangle`.
+An :dt:`exported function` is an export of a :t:`function`.
 
 :dp:`fls_I029Rvr5BX5P`
-An :t:`exported static` is a :t:`static` subject to :t:`attribute`
+An :dt:`exported static` is a :t:`static` subject to :t:`attribute`
 :c:`no_mangle`.
 
 .. rubric:: Examples
@@ -1561,6 +1562,10 @@ Attribute ``repr``
 :t:`Attribute` :dc:`repr` shall indicate the :t:`type representation` of the
 related :t:`type`.
 
+:dp:`fls_8l5b6qxw0c9d`
+A :t:`representation modifier` is a :t:`construct` that modifies the
+:t:`alignment` of a :t:`type`.
+
 .. rubric:: Examples
 
 .. code-block:: rust
@@ -1585,6 +1590,10 @@ Attribute ``unsafe``
 
 .. rubric:: Legality Rules
 
+:dp:`fls_ovn9czwnwxue`
+An :dt:`unsafe operation` is an operation that may result in
+:t:`undefined behavior` that is not diagnosed as a static error.
+
 :dp:`fls_z5DTDKM9mU3o`
 :t:`Attribute` :dc:`unsafe` is used to indicate that an  :t:`attribute` is :t:`unsafe <unsafe operation>`.
 
@@ -1845,7 +1854,8 @@ Attribute ``proc_macro``
 
 :dp:`fls_u48dtmh97g`
 :t:`Attribute` :c:`proc_macro` shall apply to public :t:`[function]s` in the
-:t:`crate root module` of a :t:`proc-macro crate`.
+:t:`crate root module` of a :t:`proc-macro crate` (a :t:`crate` whose
+:t:`crate type` is ``proc-macro``).
 
 :dp:`fls_t4ez0zg1m569`
 :t:`Attribute` :dc:`proc_macro` turns the related :t:`function` into a
@@ -1963,8 +1973,9 @@ Attribute ``path``
 :t:`Attribute` :c:`path` shall apply to :t:`[module]s`.
 
 :dp:`fls_qb6anohvc03k`
-:t:`Attribute` :dc:`path` specifies the :dt:`module path` of the respective
-:t:`module` as a :t:`string literal`.
+The :dt:`path attribute` is an :t:`attribute` (written as :c:`path`) that
+specifies the :dt:`module path` of the respective :t:`module` as a
+:t:`string literal`.
 
 :dp:`fls_18tcecx4p2wp`
 A tool is free to define the format of a :t:`module path`.
@@ -2004,7 +2015,8 @@ shall apply to the :t:`crate root module` or to :t:`[module]s`.
 
 :dp:`fls_cmrqxc5oax4r`
 The :t:`outer attribute` version of :t:`attribute` :c:`no_implicit_prelude`
-shall apply to :t:`[module]s`.
+shall apply to :t:`[module]s`, because an :t:`outer attribute` applies to a
+subsequent :t:`item`.
 
 :dp:`fls_c7v2hbdb7g2d`
 :t:`Attribute` :dc:`no_implicit_prelude` prevents the import of the

src/concurrency.rst

@@ -15,7 +15,7 @@ without :t:`[data race]s`, whose rules are presented in this chapter.
 .. rubric:: Legality Rules
 
 :dp:`fls_tx4b8r6i93n4`
-A :t:`data race` is a scenario where two or more threads access a shared memory
+A :dt:`data race` is a scenario where two or more threads access a shared memory
 location concurrently without any synchronization, where one of the accesses is
 a modification.
 
@@ -37,7 +37,7 @@ The Rust programming language provides the :std:`core::marker::Send` and
 :t:`type` level.
 
 :dp:`fls_2jujsujpjp3w`
-A :t:`send type` is a :t:`type` that implements the :std:`core::marker::Send`
+A :dt:`send type` is a :t:`type` that implements the :std:`core::marker::Send`
 :t:`trait`.
 
 :dp:`fls_cax6fe4em23k`
@@ -50,7 +50,7 @@ A :t:`send type` shall have :t:`[value]s` that are safe to transfer across
 thread boundaries.
 
 :dp:`fls_dekskhk4g895`
-A :t:`sync type` is a :t:`type` that implements the :std:`core::marker::Sync`
+A :dt:`sync type` is a :t:`type` that implements the :std:`core::marker::Sync`
 :t:`trait`.
 
 :dp:`fls_y0iqr5ibnbfe`
@@ -70,10 +70,13 @@ Atomics
 .. rubric:: Legality Rules
 
 :dp:`fls_3pjla9s93mhd`
-An :t:`atomic type` is a :t:`type` defined in :t:`module`
+An :dt:`atomic type` is a :t:`type` defined in :t:`module`
 :std:`core::sync::atomic`. :t:`[Atomic type]s` provide primitive shared-memory
 communication between threads.
 
+:dp:`fls_7r2m9q4t1c6v`
+For :dt:`atomic`, see :t:`atomic type`.
+
 :dp:`fls_wn4ynaio8u47`
 :t:`[Atomic type]s` are related to :t:`[type]s` as follows:
 
@@ -142,4 +145,3 @@ The computed :t:`value` of a :t:`future` is obtained by using an
 :dp:`fls_ftzey2156ha`
 :std:`core::future::Future::poll` shall not be invoked on a :t:`future` that has
 already returned :std:`core::task::Poll::Ready`.
-

src/conf.py

@@ -59,3 +59,13 @@
 lint_alphabetical_section_titles = ["glossary"]
 
 lint_no_paragraph_ids = ["index", "changelog"]
+
+lint_glossary_migration_phase = int(os.environ.get("FLS_GLOSSARY_MIGRATION_PHASE", "0"))
+lint_glossary_migration_strict = (
+    os.environ.get("FLS_GLOSSARY_MIGRATION_STRICT", "0") == "1"
+)
+lint_glossary_migration_report = os.environ.get("FLS_GLOSSARY_MIGRATION_REPORT", "")
+lint_glossary_migration_report_root = os.path.join(
+    os.environ.get("OPENCODE_CONFIG_DIR", "."),
+    "reports",
+)