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 |