diff options
author | sanine <sanine.not@pm.me> | 2022-08-25 14:54:53 -0500 |
---|---|---|
committer | sanine <sanine.not@pm.me> | 2022-08-25 14:54:53 -0500 |
commit | 37c97e345d12f95dde44e1d1a4c2f2aadd4615bc (patch) | |
tree | e1bb25bc855883062bdd7847ff2c04290f71c840 /portaudio/doc/utils/checkfiledocs.py | |
parent | 5634c7b04da619669f2f29f6798c03982be05180 (diff) |
add initial structure
Diffstat (limited to 'portaudio/doc/utils/checkfiledocs.py')
-rw-r--r-- | portaudio/doc/utils/checkfiledocs.py | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/portaudio/doc/utils/checkfiledocs.py b/portaudio/doc/utils/checkfiledocs.py new file mode 100644 index 0000000..5d6b585 --- /dev/null +++ b/portaudio/doc/utils/checkfiledocs.py @@ -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" ) + + |