annotate src/portaudio_20161030_catalina_patch/doc/utils/checkfiledocs.py @ 162:d43aab368df9

Duplicate for patch testing

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