Subzero: Improve the Doxygen input filter for TODO extraction.

Doxyfile

 # Doxyfile 1.8.6
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
 #
 # All text after a double hash (##) is considered a comment and is placed in
 # front of the TAG it is preceding.
 #
 # All text after a single hash (#) is considered a comment and will be ignored.
 # The format is:
@@ skipping 831 matching lines @@
 # where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the
 # name of an input file. Doxygen will then use the output that the filter
 # program writes to standard output. If FILTER_PATTERNS is specified, this tag
 # will be ignored.
 #
 # Note that the filter must not add or remove lines; it is applied before the
 # code is scanned, but not when the output code is generated. If lines are added
 # or removed, the anchors will not be placed correctly.
 
 # This script transforms TODO strings into a @todo form.  It also transforms
-# "//" into "///" (but only when there are exactly 2 '/' characters in a row).
-# The first pattern matches "//" at the beginning of the line, and the second
-# pattern matches a mid-line "//".  The third pattern matches "TODO " or
-# "TODO(owner)" or "TODO:".  This should cover the usual TODO patterns, while
-# not falsely matching e.g. a call to a function whose name ends in "TODO".
+# "//" comments into doxygen "///" comments on every line, starting from a line
+# containing a commented TODO, and ending at the next line without a comment.
 
-INPUT_FILTER           = "sed -e 's?^//\([^/]\)?///\1?' \
-                              -e 's?\([^/]\)//\([^/]\)?\1///\2?' \
-                              -e 's/ \(TODO[ (:]\)/ @todo \1/g'"
+INPUT_FILTER           = "awk '                                                \
+  { HasComment = /\/\//; HasTripleSlash = /\/\/\//; HasTodo = / TODO[ (:]/; }  \
+  HasComment && HasTodo { InTodoBlock = 1; }                                   \
+  !HasComment { InTodoBlock = 0; }                                             \
+  InTodoBlock && !HasTripleSlash { sub(\"//\", \"///\"); }                     \
+  InTodoBlock { $0 = gensub(/ (TODO[ (:])/, \" @todo \\1\", \"g\", $0); }      \
+  { print; }'"
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the
 # filter if there is a match. The filters are a list of the form: pattern=filter
 # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how
 # filters are used. If the FILTER_PATTERNS tag is empty or if none of the
 # patterns match the file name, INPUT_FILTER is applied.
 
 FILTER_PATTERNS        =
 
@@ skipping 1432 matching lines @@
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 GENERATE_LEGEND        = YES
 
 # If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot
 # files that are used to generate the various graphs.
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_CLEANUP            = YES