commit 560450f2fbce3cf6967851e51be72cfddd35d5c1 Author: Nick Mathewson nickm@torproject.org Date: Sat Mar 26 10:31:59 2016 -0400

helper script to highlight undocumented members --- scripts/maint/locatemissingdoxygen.py | 74 +++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+)

diff --git a/scripts/maint/locatemissingdoxygen.py b/scripts/maint/locatemissingdoxygen.py new file mode 100755 index 0000000..797bf81 --- /dev/null +++ b/scripts/maint/locatemissingdoxygen.py @@ -0,0 +1,74 @@ +#!/usr/bin/python + +""" + This script parses the stderr output of doxygen and looks for undocumented + stuff. By default, it just counts the undocumented things per file. But with + the -A option, it rewrites the files to stick in /*DOCDOC*/ comments + to highlight the undocumented stuff. +""" + +import os +import re +import shutil +import sys + +warning_pattern = re.compile(r'^([^:]+):(\d+): warning: (.*) is not documented') + +def readDoxygenOutput(f): + " yields (cfilename, lineno, thingname) " + for line in f: + m = warning_pattern.match(line) + if m: + yield m.groups() + +warnings = {} + +def buildWarnings(): + for fn, lineno, what in list(readDoxygenOutput(sys.stdin)): + warnings.setdefault(fn, []).append( (int(lineno), what) ) + +def count(fn): + if os.path.abspath(fn) not in warnings: + print "0\t%s"%fn + else: + n = len(warnings[os.path.abspath(fn)]) + print "%d\t%s"%(n,fn) + +def getIndentation(line): + s = line.lstrip() + return line[:len(line)-len(s)] + +def annotate(filename): + if os.path.abspath(filename) not in warnings: + return + with open(filename) as f: + lines = f.readlines() + w = warnings[os.path.abspath(filename)][:] + w.sort() + w.reverse() + + for lineno, what in w: + lineno -= 1 # list is 0-indexed. + if 'DOCDOC' in lines[lineno]: + continue + ind = getIndentation(lines[lineno]) + lines.insert(lineno, "%s/* DOCDOC %s */\n"%(ind,what)) + + shutil.copy(filename, filename+".orig") + with open(filename, 'w') as f: + for l in lines: + f.write(l) + + +if __name__ == '__main__': + if len(sys.argv) == 1: + print "Usage: locatemissingdoxygen.py [-A] filename... <doxygen_log" + sys.exit(1) + buildWarnings() + if sys.argv[1] == '-A': + del sys.argv[1] + func = annotate + else: + func = count + for fname in sys.argv[1:]: + func(fname)