[PATCH AUTOSEL 6.18-6.17] scripts: kdoc_parser.py: warn about Python version only once

[Sasha Levin <sashal@kernel.org>]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

[ Upstream commit ade9b9576e2f000fb2ef0ac3bcd26e1167fd813b ]

When running kernel-doc over multiple documents, it emits
one error message per file with is not what we want:

	$ python3.6 scripts/kernel-doc.py . --none
	...
	Warning: ./include/trace/events/swiotlb.h:0 Python 3.7 or later is required for correct results
	Warning: ./include/trace/events/iommu.h:0 Python 3.7 or later is required for correct results
	Warning: ./include/trace/events/sock.h:0 Python 3.7 or later is required for correct results
	...

Change the logic to warn it only once at the library:

	$ python3.6 scripts/kernel-doc.py . --none
	Warning: Python 3.7 or later is required for correct results
	Warning: ./include/cxl/features.h:0 Python 3.7 or later is required for correct results

When running from command line, it warns twice, but that sounds
ok.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <68e54cf8b1201d1f683aad9bc710a99421910356.1758196090.git.mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Sasha Levin <sashal@kernel.org>
---

LLM Generated explanations, may be completely bogus:

## Analysis

### 1. COMMIT MESSAGE ANALYSIS

**Subject**: `scripts: kdoc_parser.py: warn about Python version only
once`

**Problem**: When `kernel-doc` processes multiple files with Python <
3.7, it emits one warning per file, creating noise:
```
Warning: ./include/trace/events/swiotlb.h:0 Python 3.7 or later is
required for correct results
Warning: ./include/trace/events/iommu.h:0 Python 3.7 or later is
required for correct results
Warning: ./include/trace/events/sock.h:0 Python 3.7 or later is required
for correct results
...
```

**Solution**: Add a module-level flag (`python_warning`) so the warning
is emitted once per process run.

**Tags**: No "Cc: stable@vger.kernel.org" or "Fixes:" tag.

**Author**: Mauro Carvalho Chehab (kernel-doc maintainer)
**Date**: September 18, 2025

---

### 2. CODE CHANGE ANALYSIS

**Files changed**: 1 file (`scripts/lib/kdoc/kdoc_parser.py`)
**Lines changed**: +6, -1 (net +5)

**Diff**:
```python
+python_warning = False  # Module-level global flag

class KernelDoc:
    def __init__(self, config, fname):
        ...
- if sys.version_info.major == 3 and sys.version_info.minor < 7:
+        global python_warning
+        if (not python_warning and
+            sys.version_info.major == 3 and sys.version_info.minor <
7):
             self.emit_msg(0,
                           'Python 3.7 or later is required for correct
results')
+            python_warning = True
```

**Mechanism**:
- `KernelDoc.__init__()` runs once per file.
- The check was unconditional, causing repeated warnings.
- The fix adds a module-level flag set after the first warning to
  suppress subsequent ones.

**Correctness**: Correct. The flag is checked and set atomically within
the same conditional, preventing races.

---

### 3. CLASSIFICATION

**Type**: Bug fix (UX)

**Category**: Build/documentation tool fix
- Not kernel runtime code
- Affects `kernel-doc` output
- Improves developer experience

**Exception categories**: None (not device IDs, quirks, DT updates, or
build fixes)

**Security**: No security impact

---

### 4. SCOPE AND RISK ASSESSMENT

**Complexity**: Low
- Simple flag check
- No logic changes
- Minimal code

**Risk**: Very low
- Only changes warning output
- No functional changes
- No new code paths
- No dependencies on other changes

**Subsystem**: Documentation build tools (`scripts/lib/kdoc/`)
- Less critical than kernel runtime code
- Still affects developers building docs

**Files touched**: 1 file, 7 lines changed

---

### 5. USER IMPACT

**Who is affected**:
- Developers building kernel documentation
- CI/CD systems running `kernel-doc`
- Anyone using Python < 3.7 with `kernel-doc` on multiple files

**Severity**: Low–moderate
- Not a crash or data corruption
- User-visible annoyance (warning spam)
- Can obscure other warnings

**Real-world impact**: Yes
- Occurs when processing multiple files (common)
- Example: `python3.6 scripts/kernel-doc.py . --none` on a directory

**Note**: Python 3.9+ is the kernel minimum, but some systems may still
use older versions.

---

### 6. STABILITY INDICATORS

**Tested-by**: Not mentioned
**Reviewed-by**: Jonathan Corbet (kernel-doc maintainer)
**Age**: Commit from September 2025 (recent)

**Maintainer approval**: Signed-off by Jonathan Corbet (maintainer)

---

### 7. DEPENDENCY CHECK

**Prerequisite**: Requires commit `40020fe8e3a40` ("docs: kdoc: emit a
warning for ancient versions of Python") from July 2025.

**Backport implications**:
- If the prerequisite exists in a stable tree, this applies cleanly.
- If not, both commits would need to be backported together.
- The prerequisite is also a small, low-risk change.

**Code existence**: The `KernelDoc` class and the warning check exist in
current stable trees (the warning was added in 2025).

---

### 8. STABLE KERNEL RULES EVALUATION

**1. Obviously correct and tested**: Yes — simple flag check, reviewed
by maintainer
**2. Fixes a real bug**: Yes — excessive warning spam
**3. Important issue**: Moderate — UX improvement, not critical
**4. Small and contained**: Yes — 7 lines, single file
**5. No new features**: Correct — only changes warning behavior
**6. Applies cleanly**: Yes — if prerequisite exists

**Concerns**:
- Documentation tool fix (less critical than kernel code)
- Requires prerequisite commit
- UX improvement, not a critical bug

**Benefits**:
- Fixes a real user-visible issue
- Very low risk
- Small and simple
- Improves developer experience

---

### 9. FINAL ASSESSMENT

**Verdict**: YES, with conditions

**Reasoning**:
1. Fixes a real user-visible bug (excessive warnings)
2. Very low risk (warning output only)
3. Small, simple change
4. Reviewed by maintainer
5. Improves developer experience

**Conditions**:
- The prerequisite commit (`40020fe8e3a40`) must exist in the target
  stable tree, or both commits should be backported together.
- This is a UX improvement, not critical, but it addresses a real
  annoyance.

**Recommendation**: Backport to stable trees that have the prerequisite
warning commit, or backport both commits together. The low risk and
clear benefit justify inclusion.

**YES**

 scripts/lib/kdoc/kdoc_parser.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 2376f180b1fa9..89d920e0b65ca 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -350,6 +350,7 @@ class KernelEntry:
             self.section = SECTION_DEFAULT
             self._contents = []
 
+python_warning = False
 
 class KernelDoc:
     """
@@ -383,9 +384,13 @@ class KernelDoc:
         # We need Python 3.7 for its "dicts remember the insertion
         # order" guarantee
         #
-        if sys.version_info.major == 3 and sys.version_info.minor < 7:
+        global python_warning
+        if (not python_warning and
+            sys.version_info.major == 3 and sys.version_info.minor < 7):
+
             self.emit_msg(0,
                           'Python 3.7 or later is required for correct results')
+            python_warning = True
 
     def emit_msg(self, ln, msg, warning=True):
         """Emit a message"""
-- 
2.51.0