scripts/maint/locatemissingdoxygen.py

   1 #!/usr/bin/python
   2
   3 """
   4   This script parses the stderr output of doxygen and looks for undocumented
   5   stuff.  By default, it just counts the undocumented things per file.  But with
   6   the -A option, it rewrites the files to stick in /*DOCDOC*/ comments
   7   to highlight the undocumented stuff.
   8 """
   9
  10 import os
  11 import re
  12 import shutil
  13 import sys
  14
  15 warning_pattern = re.compile(r'^([^:]+):(\d+): warning: (.*) is not documented')
  16
  17 def readDoxygenOutput(f):
  18     " yields (cfilename, lineno, thingname) "
  19     for line in f:
  20         m = warning_pattern.match(line)
  21         if m:
  22             yield m.groups()
  23
  24 warnings = {}
  25
  26 def buildWarnings():
  27     for fn, lineno, what in list(readDoxygenOutput(sys.stdin)):
  28         warnings.setdefault(fn, []).append( (int(lineno), what) )
  29
  30 def count(fn):
  31     if os.path.abspath(fn) not in warnings:
  32         print "0\t%s"%fn
  33     else:
  34         n = len(warnings[os.path.abspath(fn)])
  35         print "%d\t%s"%(n,fn)
  36
  37 def getIndentation(line):
  38     s = line.lstrip()
  39     return line[:len(line)-len(s)]
  40
  41 def annotate(filename):
  42     if os.path.abspath(filename) not in warnings:
  43         return
  44     with open(filename) as f:
  45         lines = f.readlines()
  46     w = warnings[os.path.abspath(filename)][:]
  47     w.sort()
  48     w.reverse()
  49
  50     for lineno, what in w:
  51         lineno -= 1 # list is 0-indexed.
  52         if 'DOCDOC' in lines[lineno]:
  53             continue
  54         ind = getIndentation(lines[lineno])
  55         lines.insert(lineno, "%s/* DOCDOC %s */\n"%(ind,what))
  56
  57     shutil.copy(filename, filename+".orig")
  58     with open(filename, 'w') as f:
  59         for l in lines:
  60             f.write(l)
  61
  62
  63 if __name__ == '__main__':
  64     if len(sys.argv) == 1:
  65         print "Usage: locatemissingdoxygen.py [-A] filename... <doxygen_log"
  66         sys.exit(1)
  67     buildWarnings()
  68     if sys.argv[1] == '-A':
  69         del sys.argv[1]
  70         func = annotate
  71     else:
  72         func = count
  73     for fname in sys.argv[1:]:
  74         func(fname)