commit 0b367f3386b0ec25f85716001690c95ae2e78c4d Author: Nick Mathewson <nickm@torproject.org> Date: Wed Sep 18 10:41:05 2019 -0400 Add comments to annotate_ifdef_directives --- scripts/maint/annotate_ifdef_directives | 40 +++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/scripts/maint/annotate_ifdef_directives b/scripts/maint/annotate_ifdef_directives index ca267a865..15121652d 100755 --- a/scripts/maint/annotate_ifdef_directives +++ b/scripts/maint/annotate_ifdef_directives @@ -2,21 +2,54 @@ # Copyright (c) 2017-2019, The Tor Project, Inc. # See LICENSE for licensing information +# This script iterates over a list of C files. For each file, it looks at the +# #if/#else C macros, and annotates them with comments explaining what they +# match. +# +# For example, it replaces this: +# +# #ifdef HAVE_OCELOT +# // 500 lines of ocelot code +# #endif +# +# with this: +# +# #ifdef HAVE_OCELOT +# // 500 lines of ocelot code +# #endif /* defined(HAVE_OCELOT) */ +# +# Note that only #else and #endif lines are annotated. Existing comments +# on those lines are removed. + import re +# Any block with fewer than this many lines does not need annotations. LINE_OBVIOUSNESS_LIMIT = 4 class Problem(Exception): pass def uncomment(s): + """ + Remove existing trailing comments from an #else or #endif line. + """ s = re.sub(r'//.*','',s) s = re.sub(r'/\*.*','',s) return s.strip() def translate(f_in, f_out): - whole_file = [] + """ + Read a file from f_in, and write its annotated version to f_out. + """ + # A stack listing our current if/else state. Each member of the stack + # is a list of directives. Each directive is a 3-tuple of + # (command, rest, lineno) + # where "command" is one of if/ifdef/ifndef/else/elif, and where + # "rest" is an expression in a format suitable for use with #if, and where + # lineno is the line number where the directive occurred. stack = [] + # the stack element corresponding to the top level of the file. + whole_file = [] cur_level = whole_file lineno = 0 for line in f_in: @@ -24,6 +57,7 @@ def translate(f_in, f_out): m = re.match(r'\s*#\s*(if|ifdef|ifndef|else|endif|elif)\b\s*(.*)', line) if not m: + # no directive, so we can just write it out. f_out.write(line) continue command,rest = m.groups() @@ -43,6 +77,8 @@ def translate(f_in, f_out): cur_level = new_level f_out.write(line) elif command in ("else", "elif"): + # We stay at the same level on the stack. If we have an #else, + # we comment it. if len(cur_level) == 0 or cur_level[-1][0] == 'else': raise Problem("Unexpected #%s on %d"% (command,lineno)) if (len(cur_level) == 1 and command == 'else' and @@ -52,6 +88,7 @@ def translate(f_in, f_out): f_out.write(line) cur_level.append((command, rest, lineno)) else: + # We pop one element on the stack, and comment an endif. assert command == 'endif' if len(stack) == 0: raise Problem("Unmatched #%s on %s"% (command,lineno)) @@ -71,4 +108,3 @@ for fn in sys.argv[1:]: with open(fn+"_OUT", 'w') as output_file: translate(open(fn, 'r'), output_file) os.rename(fn+"_OUT", fn) -