diff options
Diffstat (limited to 'contrib/redox.py')
-rwxr-xr-x | contrib/redox.py | 215 |
1 files changed, 0 insertions, 215 deletions
diff --git a/contrib/redox.py b/contrib/redox.py deleted file mode 100755 index e9914dab18..0000000000 --- a/contrib/redox.py +++ /dev/null @@ -1,215 +0,0 @@ -#!/usr/bin/python -# -# Copyright (c) 2008-2013, 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. -# -# So, here's your workflow: -# -# 0. Make sure you're running a bourne shell for the redirects below. -# 1. make doxygen 1>doxygen.stdout 2>doxygen.stderr. -# 2. grep Warning doxygen.stderr | grep -v 'is not documented' | less -# [This will tell you about all the bogus doxygen output you have] -# 3. python ./contrib/redox.py <doxygen.stderr -# [This will make lots of .newdoc files with DOCDOC comments for -# whatever was missing documentation.] -# 4. Look over those .newdoc files, and see which docdoc comments you -# want to merge into the main file. If it's all good, just run -# "mv fname.c.newdoc fname.c". Otherwise, you'll need to merge -# the parts you like by hand. - -# Which files should we ignore warning from? Mostly, these are external -# files that we've snarfed in from somebody else, whose C we do no intend -# to document for them. -SKIP_FILES = [ "OpenBSD_malloc_Linux.c", - "eventdns.c", - "eventdns.h", - "strlcat.c", - "strlcpy.c", - "sha256.c", - "sha256.h", - "aes.c", - "aes.h" ] - -# What names of things never need javadoc -SKIP_NAME_PATTERNS = [ r'^.*_c_id$', - r'^.*_H_ID$' ] - -# Which types of things should get DOCDOC comments added if they are -# missing documentation? Recognized types are in KINDS below. -ADD_DOCDOCS_TO_TYPES = [ 'function', 'type', 'typedef' ] -ADD_DOCDOCS_TO_TYPES += [ 'variable', ] - -# ==================== -# The rest of this should not need hacking. - -import re -import sys - -KINDS = [ "type", "field", "typedef", "define", "function", "variable", - "enumeration" ] - -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|enumeration)\) of (file|class) ') - -SKIP_NAMES = [re.compile(s) for s in SKIP_NAME_PATTERNS] - -def parsething(thing): - """I figure out what 'foobar baz in quux quum is not documented' means, - and return: the name of the foobar, and the kind of the foobar. - """ - if thing.startswith("Compound "): - tp, name = "type", thing.split()[1] - else: - m = THING_RE.match(thing) - if not m: - print thing, "???? Format didn't match." - 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(): - """I snarf doxygen stderr from stdin, and parse all the "foo has no - documentation messages. I return a map from filename to lists - of tuples of (alleged line number, name of thing, kind of thing) - """ - errs = {} - for line in sys.stdin: - m = NODOC_LINE_RE.match(line) - if m: - file, line, tp, thing = m.groups() - assert tp.lower() == 'warning' - name, kind = parsething(thing) - errs.setdefault(file, []).append((int(line), name, kind)) - - return errs - -def findline(lines, lineno, ident): - """Given a list of all the lines in the file (adjusted so 1-indexing works), - a line number that ident is alledgedly on, and ident, I figure out - the line where ident was really declared.""" - 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): - """I return true if it looks like there's already a good comment about - the thing on lineno of lines of type 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): - """I return true if it looks like there's already a docdoc comment about - the thing on lineno of lines of type 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): - """I go through the output of read() for a single file, and build a list - of tuples of things that want DOCDOC comments. Each tuple has: - the line number where the comment goes; the kind of thing; its name. - """ - for skip in SKIP_FILES: - if fn.endswith(skip): - print "Skipping",fn - return - - comments = [] - 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.append((ln, kind, name)) - - return comments - -def applyComments(fn, entries): - """I apply lots of comments to the file in fn, making a new .newdoc file. - """ - N = 0 - - lines = [ None ] - try: - lines.extend( open(fn, 'r').readlines() ) - except IOError: - return - - # Process the comments in reverse order by line number, so that - # the line numbers for the ones we haven't added yet remain valid - # until we add them. Standard trick. - 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() - -for fn, errs in e.iteritems(): - comments = checkf(fn, errs) - if comments: - applyComments(fn, comments) |