The glibc library limits the return code to 8 bits. We need to
stick to this limit when using sys.exit(error_count).

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: stable@vger.kernel.org
---
 scripts/kernel-doc.py | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 7a1eaf986bcd..5d2f29e90ebe 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -116,6 +116,8 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
 
 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
 
+WERROR_RETURN_CODE = 3
+
 DESC = """
 Read C language source or header FILEs, extract embedded documentation comments,
 and print formatted documentation to standard output.
@@ -176,7 +178,21 @@ class MsgFormatter(logging.Formatter):
         return logging.Formatter.format(self, record)
 
 def main():
-    """Main program"""
+    """
+    Main program
+    By default, the return value is:
+
+    - 0: parsing warnings or Python version is not compatible with
+      kernel-doc. The rationale for the latter is to not break Linux
+      compilation on such cases;
+
+    - 1: an abnormal condition happened;
+
+    - 2: arparse issued an error;
+
+    - 3: -Werror is used, and one or more unfiltered parse warnings
+         happened.
+    """
 
     parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
                                      description=DESC)
@@ -323,16 +339,12 @@ def main():
 
     if args.werror:
         print("%s warnings as errors" % error_count)    # pylint: disable=C0209
-        sys.exit(error_count)
+        sys.exit(WERROR_RETURN_CODE)
 
     if args.verbose:
         print("%s errors" % error_count)                # pylint: disable=C0209
 
-    if args.none:
-        sys.exit(0)
-
-    sys.exit(error_count)
-
+    sys.exit(0)
 
 # Call main method
 if __name__ == "__main__":
-- 
2.52.0

On 1/13/26 9:19 AM, Mauro Carvalho Chehab wrote:
> The glibc library limits the return code to 8 bits. We need to
> stick to this limit when using sys.exit(error_count).
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: stable@vger.kernel.org
> ---
>  scripts/kernel-doc.py | 26 +++++++++++++++++++-------
>  1 file changed, 19 insertions(+), 7 deletions(-)
> 
> diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
> index 7a1eaf986bcd..5d2f29e90ebe 100755
> --- a/scripts/kernel-doc.py
> +++ b/scripts/kernel-doc.py
> @@ -116,6 +116,8 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
>  
>  sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
>  
> +WERROR_RETURN_CODE = 3
> +
>  DESC = """
>  Read C language source or header FILEs, extract embedded documentation comments,
>  and print formatted documentation to standard output.
> @@ -176,7 +178,21 @@ class MsgFormatter(logging.Formatter):
>          return logging.Formatter.format(self, record)
>  
>  def main():
> -    """Main program"""
> +    """
> +    Main program
> +    By default, the return value is:
> +
> +    - 0: parsing warnings or Python version is not compatible with
> +      kernel-doc. The rationale for the latter is to not break Linux
> +      compilation on such cases;

    Does "parsing warnings" mean that there were no errors, just possibly
    warnings or possibly nothing, i.e., all clean?

> +
> +    - 1: an abnormal condition happened;
> +
> +    - 2: arparse issued an error;

            argparse ?

> +
> +    - 3: -Werror is used, and one or more unfiltered parse warnings
> +         happened.
> +    """
>  
>      parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
>                                       description=DESC)
> @@ -323,16 +339,12 @@ def main():
>  
>      if args.werror:
>          print("%s warnings as errors" % error_count)    # pylint: disable=C0209
> -        sys.exit(error_count)
> +        sys.exit(WERROR_RETURN_CODE)
>  
>      if args.verbose:
>          print("%s errors" % error_count)                # pylint: disable=C0209
>  
> -    if args.none:
> -        sys.exit(0)
> -
> -    sys.exit(error_count)
> -
> +    sys.exit(0)
>  
>  # Call main method
>  if __name__ == "__main__":

-- 
~Randy