gearmulator

Emulation of classic VA synths of the late 90s/2000s that are based on Motorola 56300 family DSPs
Log | Files | Refs | Submodules | README | LICENSE

checkfiledocs.py (2789B)

      1 import os
      2 import os.path
      3 import string
      4 
      5 paRootDirectory = '../../'
      6 paHtmlDocDirectory = os.path.join( paRootDirectory, "doc", "html" )
      7 
      8 ## Script to check documentation status
      9 ## this script assumes that html doxygen documentation has been generated
     10 ##
     11 ## it then walks the entire portaudio source tree and check that
     12 ## - every source file (.c,.h,.cpp) has a doxygen comment block containing
     13 ##	- a @file directive
     14 ##	- a @brief directive
     15 ##	- a @ingroup directive
     16 ## - it also checks that a corresponding html documentation file has been generated.
     17 ##
     18 ## This can be used as a first-level check to make sure the documentation is in order.
     19 ##
     20 ## The idea is to get a list of which files are missing doxygen documentation.
     21 ##
     22 ## How to run:
     23 ##  $ cd doc/utils
     24 ##  $ python checkfiledocs.py
     25 
     26 def oneOf_a_in_b(a, b):
     27     for x in a:
     28         if x in b:
     29             return True
     30     return False
     31 
     32 # recurse from top and return a list of all with the given
     33 # extensions. ignore .svn directories. return absolute paths
     34 def recursiveFindFiles( top, extensions, dirBlacklist, includePaths ):
     35     result = []
     36     for (dirpath, dirnames, filenames) in os.walk(top):
     37         if not oneOf_a_in_b(dirBlacklist, dirpath):
     38             for f in filenames:
     39                 if os.path.splitext(f)[1] in extensions:
     40                     if includePaths:
     41                         result.append( os.path.abspath( os.path.join( dirpath, f ) ) )
     42                     else:
     43                         result.append( f )
     44     return result
     45 
     46 # generate the html file name that doxygen would use for
     47 # a particular source file. this is a brittle conversion
     48 # which i worked out by trial and error
     49 def doxygenHtmlDocFileName( sourceFile ):
     50     return sourceFile.replace( '_', '__' ).replace( '.', '_8' ) + '.html'
     51 
     52 
     53 sourceFiles = recursiveFindFiles( os.path.join(paRootDirectory,'src'), [ '.c', '.h', '.cpp' ], ['.svn', 'mingw-include'], True );
     54 sourceFiles += recursiveFindFiles( os.path.join(paRootDirectory,'include'), [ '.c', '.h', '.cpp' ], ['.svn'], True );
     55 docFiles = recursiveFindFiles( paHtmlDocDirectory, [ '.html' ], ['.svn'], False );
     56 
     57 
     58 
     59 currentFile = ""
     60 
     61 def printError( f, message ):
     62     global currentFile
     63     if f != currentFile:
     64         currentFile = f
     65         print f, ":"
     66     print "\t!", message
     67 
     68 
     69 for f in sourceFiles:
     70     if not doxygenHtmlDocFileName( os.path.basename(f) ) in docFiles:
     71         printError( f, "no doxygen generated doc page" )
     72 
     73     s = file( f, 'rt' ).read()
     74 
     75     if not '/**' in s:
     76         printError( f, "no doxygen /** block" )  
     77     
     78     if not '@file' in s:
     79         printError( f, "no doxygen @file tag" )
     80 
     81     if not '@brief' in s:
     82         printError( f, "no doxygen @brief tag" )
     83         
     84     if not '@ingroup' in s:
     85         printError( f, "no doxygen @ingroup tag" )
     86         
     87