Ignore unknown marked messages in the manpage diagnostics
Marco Ricci

Marco Ricci commited on 2025-08-22 07:01:55
Zeige 1 geänderte Dateien mit 10 Einfügungen und 5 Löschungen.


When computing the set of unknown-but-documented error, warning and info
messages in the manual pages, ignore messages that are merely marked in
the manpages.

We use this mechanism to indicate discontinued messages that no longer
have a source counterpart, but should still be documented as historic
messages.

(Marked messages are also used for other purposes, such as sets of
messages that are distinguished at the source code level, but do not
require separate documentation entries because they are so similar.
A marked message does not automatically indicate that it is no longer
present in the source code.)
... ...
@@ -24,6 +24,8 @@ if TYPE_CHECKING:
24 24
 known_errors = cli_messages.ErrMsgTemplate.__members__
25 25
 known_warnings = cli_messages.WarnMsgTemplate.__members__
26 26
 
27
+mark_only = cast("DiagnosticText", "<mark only>")
28
+
27 29
 
28 30
 def _replace_known_metavars(string: str) -> str:
29 31
     return (
... ...
@@ -142,7 +144,7 @@ def _entries_from_mark_only(
142 144
         tuple[DiagnosticText, EnumName],
143 145
     ]
144 146
 ]:
145
-    text = cast("DiagnosticText", "<mark only>")
147
+    text = mark_only
146 148
     _class_name, dot, enum_entry = name.partition(".")
147 149
     assert dot == ".", f"Invalid enum name {name!r}"
148 150
     assert "." not in enum_entry, f"Unsupported enum name {name!r}"
... ...
@@ -196,6 +198,7 @@ manpage_documented_errors: dict[EnumName, DiagnosticText] = {}
196 198
 manpage_documented_warnings: dict[EnumName, DiagnosticText] = {}
197 199
 manpagedoc_documented_errors: dict[EnumName, DiagnosticText] = {}
198 200
 manpagedoc_documented_warnings: dict[EnumName, DiagnosticText] = {}
201
+marks: set[EnumName] = set()
199 202
 for set_name, globs, errors, warnings in [
200 203
     (
201 204
         "manpages",
... ...
@@ -224,6 +227,8 @@ for set_name, globs, errors, warnings in [
224 227
             _check_manpage if set_name == "manpages" else _check_manpagedoc
225 228
         )
226 229
         for diagnostic_type, (text, name) in checker(path):
230
+            if text == mark_only:
231
+                marks.add(name)
227 232
             if diagnostic_type == "warning":
228 233
                 warnings[name] = text
229 234
                 print(f"DOC WARN {name} {text!r}")
... ...
@@ -238,13 +243,13 @@ for set_name, globs, errors, warnings in [
238 243
         f"Some warning messages aren't documented in the {set_name}: "
239 244
         + repr(set(known_warnings) - set(warnings))
240 245
     )
241
-    assert set(errors) <= set(known_errors), (
246
+    assert set(errors) - marks <= set(known_errors), (
242 247
         f"Some unknown error messages are documented in the {set_name}: "
243
-        + repr(set(errors) - set(known_errors))  # type: ignore[arg-type]
248
+        + repr(set(errors) - marks - set(known_errors))  # type: ignore[arg-type]
244 249
     )
245
-    assert set(warnings) <= set(known_warnings), (
250
+    assert set(warnings) - marks <= set(known_warnings), (
246 251
         f"Some unknown warning messages are documented in the {set_name}: "
247
-        + repr(set(warnings) - set(known_warnings))  # type: ignore[arg-type]
252
+        + repr(set(warnings) - marks - set(known_warnings))  # type: ignore[arg-type]
248 253
     )
249 254
 
250 255
 py_file_errors: set[EnumName] = set()
251 256