aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--contrib/redox.py168
1 files changed, 168 insertions, 0 deletions
diff --git a/contrib/redox.py b/contrib/redox.py
new file mode 100644
index 000000000..1ba36759c
--- /dev/null
+++ b/contrib/redox.py
@@ -0,0 +1,168 @@
+#!/usr/bin/python
+#
+# Copyright (c) 2008 The Tor Project, Inc.
+# See LICENSE for licensing information.
+#
+# Hi!
+# I'm redox.py, the Tor redocumentation tool!
+# I am a horrible hack!
+# I read the output of doxygen from stderr, and add missing DOCDOC comments
+# to tell you where documentation should go!
+# To use me, edit the stuff below...
+# ...and run 'make doxygen 2>doxygen.stderr' ...
+# ...and run ./contrib/redox.py < doxygen.stderr !
+# I'll make a bunch of new files by adding missing DOCDOC comments to your
+# source. Those files will have names like ./src/common/util.c.newdoc.
+# You will want to look over the changes by hand before checking them in.
+
+SKIP_FILES = [ "OpenBSD_malloc_Linux.c",
+ "eventdns.c",
+ "eventdns.h",
+ "strlcat.c",
+ "strlcpy.c",
+ "aes.c",
+ "aes.h" ]
+
+SKIP_NAME_PATTERNS = [ r'^.*_c_id$' ]
+
+ADD_DOCDOCS_TO_TYPES = [ 'function', 'type', 'typedef' ]
+# ADD_DOCDOCS_TO_TYPES += [ 'variable', 'define' ]
+
+# ====================
+# The rest of this should not need hacking.
+
+import re
+import sys
+
+KINDS = [ "type", "field", "typedef", "define", "function", "variable" ]
+
+NODOC_LINE_RE = re.compile(r'^([^:]+):(\d+): (\w+): (.*) is not documented\.$')
+
+THING_RE = re.compile(r'^Member ([a-zA-Z0-9_]+).*\((typedef|define|function|variable)\) of (file|class) ')
+
+SKIP_NAMES = [re.compile(s) for s in SKIP_NAME_PATTERNS]
+
+def parsething(thing):
+ if thing.startswith("Compound "):
+ tp, name = "type", thing.split()[1]
+ else:
+ m = THING_RE.match(thing)
+ if not m:
+ print thing
+ return None, None
+ else:
+ name, tp, parent = m.groups()
+ if parent == 'class':
+ if tp == 'variable' or tp == 'function':
+ tp = 'field'
+
+ return name, tp
+
+def read():
+ errs = {}
+ for line in sys.stdin:
+ m = NODOC_LINE_RE.match(line)
+ if m:
+ file, line, tp, thing = m.groups()
+ assert tp == 'Warning'
+ name, kind = parsething(thing)
+ errs.setdefault(file, []).append((int(line), name, kind))
+
+ return errs
+
+def findline(lines, lineno, ident):
+ for lineno in xrange(lineno, 0, -1):
+ if ident in lines[lineno]:
+ return lineno
+
+ return None
+
+FUNC_PAT = re.compile(r"^[A-Za-z0-9_]+\(")
+
+def hascomment(lines, lineno, kind):
+ if "*/" in lines[lineno-1]:
+ return True
+ if kind == 'function' and FUNC_PAT.match(lines[lineno]):
+ if "*/" in lines[lineno-2]:
+ return True
+ return False
+
+def hasdocdoc(lines, lineno, kind):
+ if "DOCDOC" in lines[lineno] or "DOCDOC" in lines[lineno-1]:
+ return True
+ if kind == 'function' and FUNC_PAT.match(lines[lineno]):
+ if "DOCDOC" in lines[lineno-2]:
+ return True
+ return False
+
+def checkf(fn, errs, comments):
+
+ for skip in SKIP_FILES:
+ if fn.endswith(skip):
+ print "Skipping",fn
+ return
+
+ lines = [ None ]
+ try:
+ lines.extend( open(fn, 'r').readlines() )
+ except IOError:
+ return
+
+ for line, name, kind in errs:
+ if any(pat.match(name) for pat in SKIP_NAMES):
+ continue
+
+ if kind not in ADD_DOCDOCS_TO_TYPES:
+ continue
+
+ ln = findline(lines, line, name)
+ if ln == None:
+ print "Couldn't find the definition of %s allegedly on %s of %s"%(
+ name, line, fn)
+ else:
+ if hasdocdoc(lines, line, kind):
+# print "Has a DOCDOC"
+# print fn, line, name, kind
+# print "\t",lines[line-2],
+# print "\t",lines[line-1],
+# print "\t",lines[line],
+# print "-------"
+ pass
+ else:
+ if kind == 'function' and FUNC_PAT.match(lines[ln]):
+ ln = ln - 1
+
+ comments.setdefault(fn, []).append((ln, kind, name))
+
+def applyComments(fn, entries):
+ N = 0
+
+ lines = [ None ]
+ try:
+ lines.extend( open(fn, 'r').readlines() )
+ except IOError:
+ return
+
+ entries.sort()
+ entries.reverse()
+
+ for ln, kind, name in entries:
+
+ lines.insert(ln, "/* DOCDOC %s */\n"%name)
+ N += 1
+
+ outf = open(fn+".newdoc", 'w')
+ for line in lines[1:]:
+ outf.write(line)
+ outf.close()
+
+ print "Added %s DOCDOCs to %s" %(N, fn)
+
+e = read()
+comments = {}
+
+for fn, errs in e.iteritems():
+ checkf(fn, errs, comments)
+
+for fn, entries in comments.iteritems():
+ applyComments(fn, entries)