commit: 3ffbd0e34f5e5698fef0302eb72dc2c2c09333cd
Author: Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
AuthorDate: Sun Feb 1 17:19:38 2026 +0000
Commit: Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
CommitDate: Sun Feb 1 17:19:38 2026 +0000
URL:
https://gitweb.gentoo.org/proj/pkgcore/pkgcheck.git/commit/?id=3ffbd0e3
EclassDocMissingInternal: new check for missing @INTERNAL
Requested-by: Ulrich Müller <ulm <AT> gentoo.org>
Signed-off-by: Arthur Zamarin <arthurzam <AT> gentoo.org>
src/pkgcheck/checks/eclass.py | 30 ++++++++++++++++++++++++++++--
1 file changed, 28 insertions(+), 2 deletions(-)
diff --git a/src/pkgcheck/checks/eclass.py b/src/pkgcheck/checks/eclass.py
index 5a6b6430..e8ab8434 100644
--- a/src/pkgcheck/checks/eclass.py
+++ b/src/pkgcheck/checks/eclass.py
@@ -435,17 +435,37 @@ class EclassDocMissingVar(results.EclassResult,
results.Warning):
return f"{self.eclass}: undocumented variable{s}: {variables}"
+class EclassDocMissingInternal(results.EclassResult, results.Warning):
+ """Eclass function missing an @INTERNAL doc tag.
+
+ Eclass functions with a leading underscore should be documented with the
+ ``@INTERNAL`` doc tag to indicate they are not part of the public API,
+ since Gentoo's convention is that leading underscores indicate internal
use.
+ """
+
+ whitelist = frozenset({"_elibtoolize"})
+
+ def __init__(self, function: str, **kwargs):
+ super().__init__(**kwargs)
+ self.function = function
+
+ @property
+ def desc(self):
+ return f"{self.eclass}: {self.function!r} starts with '_' but is not
labeled as internal"
+
+
class EclassCheck(Check):
"""Scan eclasses for various issues."""
_source = sources.EclassRepoSource
known_results = frozenset(
- [
+ {
EclassBashSyntaxError,
EclassDocError,
EclassDocMissingFunc,
EclassDocMissingVar,
- ]
+ EclassDocMissingInternal,
+ }
)
def __init__(self, *args):
@@ -501,6 +521,12 @@ class EclassCheck(Check):
if vars_missing_docs:
yield EclassDocMissingVar(sorted(vars_missing_docs), eclass=eclass)
+ missing_internal = {
+ f.name for f in eclass_obj.functions if f.name.startswith("_") and
not f.internal
+ } - EclassDocMissingInternal.whitelist
+ for f in sorted(missing_internal):
+ yield EclassDocMissingInternal(f, eclass=eclass)
+
class GoMissingDeps(results.VersionResult, results.Warning):
"""Package sets ``GO_OPTIONAL`` but does not depend on ``dev-lang/go``."""
