diff src/portaudio_20161030_catalina_patch/doc/utils/checkfiledocs.py @ 77:4edcd14160a5 pa_catalina

Duplicate for patch testing

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/portaudio_20161030_catalina_patch/doc/utils/checkfiledocs.py	Wed Oct 30 11:25:10 2019 +0000
@@ -0,0 +1,87 @@
+import os
+import os.path
+import string
+
+paRootDirectory = '../../'
+paHtmlDocDirectory = os.path.join( paRootDirectory, "doc", "html" )
+
+## Script to check documentation status
+## this script assumes that html doxygen documentation has been generated
+##
+## it then walks the entire portaudio source tree and check that
+## - every source file (.c,.h,.cpp) has a doxygen comment block containing
+##	- a @file directive
+##	- a @brief directive
+##	- a @ingroup directive
+## - it also checks that a corresponding html documentation file has been generated.
+##
+## This can be used as a first-level check to make sure the documentation is in order.
+##
+## The idea is to get a list of which files are missing doxygen documentation.
+##
+## How to run:
+##  $ cd doc/utils
+##  $ python checkfiledocs.py
+
+def oneOf_a_in_b(a, b):
+    for x in a:
+        if x in b:
+            return True
+    return False
+
+# recurse from top and return a list of all with the given
+# extensions. ignore .svn directories. return absolute paths
+def recursiveFindFiles( top, extensions, dirBlacklist, includePaths ):
+    result = []
+    for (dirpath, dirnames, filenames) in os.walk(top):
+        if not oneOf_a_in_b(dirBlacklist, dirpath):
+            for f in filenames:
+                if os.path.splitext(f)[1] in extensions:
+                    if includePaths:
+                        result.append( os.path.abspath( os.path.join( dirpath, f ) ) )
+                    else:
+                        result.append( f )
+    return result
+
+# generate the html file name that doxygen would use for
+# a particular source file. this is a brittle conversion
+# which i worked out by trial and error
+def doxygenHtmlDocFileName( sourceFile ):
+    return sourceFile.replace( '_', '__' ).replace( '.', '_8' ) + '.html'
+
+
+sourceFiles = recursiveFindFiles( os.path.join(paRootDirectory,'src'), [ '.c', '.h', '.cpp' ], ['.svn', 'mingw-include'], True );
+sourceFiles += recursiveFindFiles( os.path.join(paRootDirectory,'include'), [ '.c', '.h', '.cpp' ], ['.svn'], True );
+docFiles = recursiveFindFiles( paHtmlDocDirectory, [ '.html' ], ['.svn'], False );
+
+
+
+currentFile = ""
+
+def printError( f, message ):
+    global currentFile
+    if f != currentFile:
+        currentFile = f
+        print f, ":"
+    print "\t!", message
+
+
+for f in sourceFiles:
+    if not doxygenHtmlDocFileName( os.path.basename(f) ) in docFiles:
+        printError( f, "no doxygen generated doc page" )
+
+    s = file( f, 'rt' ).read()
+
+    if not '/**' in s:
+        printError( f, "no doxygen /** block" )  
+    
+    if not '@file' in s:
+        printError( f, "no doxygen @file tag" )
+
+    if not '@brief' in s:
+        printError( f, "no doxygen @brief tag" )
+        
+    if not '@ingroup' in s:
+        printError( f, "no doxygen @ingroup tag" )
+        
+