gendynapi.py: always check comment formatting of the public api

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 @@ if __name__ == '__main__':
 
     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()