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"""