From 6763369f5be63c0f1afcb591fc9df49fbe7c0911 Mon Sep 17 00:00:00 2001
From: Sylvain <[EMAIL REDACTED]>
Date: Fri, 7 Jul 2023 21:53:04 +0200
Subject: [PATCH] gendynapi.py: always check comment formatting of the public
api
---
src/dynapi/gendynapi.py | 127 ++++++++++++++++++++++------------------
1 file changed, 71 insertions(+), 56 deletions(-)
diff --git a/src/dynapi/gendynapi.py b/src/dynapi/gendynapi.py
index 526f543c8964..a87b46c19e4f 100755
--- a/src/dynapi/gendynapi.py
+++ b/src/dynapi/gendynapi.py
@@ -335,66 +335,82 @@ def full_API_json():
json.dump(full_API, f, indent=4, sort_keys=True)
print("dump API to '%s'" % filename);
-# Dump API into a json file
-def check_comment():
- if args.check_comment:
- print("check comment formatting");
-
-
- # Check \param
- for i in full_API:
- comment = i['comment']
- name = i['name']
- retval = i['retval']
- header = i['header']
-
- expected = len(i['parameter'])
- if expected == 1:
- if i['parameter'][0] == 'void':
- expected = 0;
- count = comment.count("\\param")
- if count != expected:
- # skip SDL_stdinc.h
- if header != 'SDL_stdinc.h':
- # Warning mismatch \param and function prototype
- print("%s: %s() %d '\\param'' but expected %d" % (header, name, count, expected));
-
-
- # Check \returns
- for i in full_API:
- comment = i['comment']
- name = i['name']
- retval = i['retval']
- header = i['header']
-
- expected = 1
- if retval == 'void':
- expected = 0;
+# Check public function comments are correct
+def check_comment_header():
+ if not check_comment_header.done:
+ check_comment_header.done = True
+ print("")
+ print("Please fix following warning(s):")
+ print("-------------------------------")
- count = comment.count("\\returns")
- if count != expected:
- # skip SDL_stdinc.h
- if header != 'SDL_stdinc.h':
- # Warning mismatch \param and function prototype
- print("%s: %s() %d '\\returns'' but expected %d" % (header, name, count, expected));
- # Check \since
- for i in full_API:
- comment = i['comment']
- name = i['name']
- retval = i['retval']
- header = i['header']
-
- expected = 1
- count = comment.count("\\since")
- if count != expected:
- # skip SDL_stdinc.h
- if header != 'SDL_stdinc.h':
- # Warning mismatch \param and function prototype
- print("%s: %s() %d '\\since'' but expected %d" % (header, name, count, expected));
+def check_comment():
+ check_comment_header.done = False
+ # Check \param
+ for i in full_API:
+ comment = i['comment']
+ name = i['name']
+ retval = i['retval']
+ header = i['header']
+ expected = len(i['parameter'])
+ if expected == 1:
+ if i['parameter'][0] == 'void':
+ expected = 0;
+ count = comment.count("\\param")
+ if count != expected:
+ # skip SDL_stdinc.h
+ if header != 'SDL_stdinc.h':
+ # Warning mismatch \param and function prototype
+ check_comment_header()
+ print(" In file %s: function %s() has %d '\\param' but expected %d" % (header, name, count, expected));
+
+ # Warning check \param uses the correct parameter name
+ # skip SDL_stdinc.h
+ if header != 'SDL_stdinc.h':
+ parameter_name = i['parameter_name']
+ for n in parameter_name:
+ if n != "" and "\\param " + n not in comment:
+ check_comment_header()
+ print(" In file %s: function %s() missing '\\param %s'" % (header, name, n));
+
+
+ # Check \returns
+ for i in full_API:
+ comment = i['comment']
+ name = i['name']
+ retval = i['retval']
+ header = i['header']
+
+ expected = 1
+ if retval == 'void':
+ expected = 0;
+
+ count = comment.count("\\returns")
+ if count != expected:
+ # skip SDL_stdinc.h
+ if header != 'SDL_stdinc.h':
+ # Warning mismatch \param and function prototype
+ check_comment_header()
+ print(" In file %s: function %s() has %d '\\returns' but expected %d" % (header, name, count, expected));
+
+ # Check \since
+ for i in full_API:
+ comment = i['comment']
+ name = i['name']
+ retval = i['retval']
+ header = i['header']
+
+ expected = 1
+ count = comment.count("\\since")
+ if count != expected:
+ # skip SDL_stdinc.h
+ if header != 'SDL_stdinc.h':
+ # Warning mismatch \param and function prototype
+ check_comment_header()
+ print(" In file %s: function %s() has %d '\\since' but expected %d" % (header, name, count, expected));
@@ -529,7 +545,6 @@ def add_dyn_api(proc):
parser = argparse.ArgumentParser()
parser.add_argument('--dump', help='output all SDL API into a .json file', action='store_true')
- parser.add_argument('--check-comment', help='check comment formatting', action='store_true')
parser.add_argument('--debug', help='add debug traces', action='store_true')
args = parser.parse_args()