annotate src/portaudio_20161030_catalina_patch/doc/utils/checkfiledocs.py @ 83:ae30d91d2ffe

Replace these with versions built using an older toolset (so as to avoid ABI compatibilities when linking on Ubuntu 14.04 for packaging purposes)

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" )