Improved docs on includeGuardRoots and improved include guard generation

Made include guard generation use longest matching root and fixed
duplicated underscores in include guards.

Author: calcmogul

.styleguide

@@ -20,8 +20,10 @@ licenseUpdateExclude {
   Excluded\.h$
 }
 
+# Ordered this way to ensure tests find longest match
 includeGuardRoots {
   wpiformat/
+  wpiformat/Test/
 }
 
 # Used by unit tests

wpiformat/README.rst

@@ -45,7 +45,9 @@ File names matching regexes in the group ``licenseUpdateExclude`` will be skippe
 
 Empty config groups can be omitted. Directory separators must be "/", not "\". During processing, they will be replaced internally with an os.sep that is automatically escaped for regexes.
 
-Valid include guard patterns use capital letters, start with the repository name, include the path to the file and the file name itself, and have directory separators and hyphens replaced with underscores. The path to the file starts from the repository root by default. Other paths, such as include directories, can be specified in the group ``includeGuardRoots``. If a path matches, that string will be truncated from the include guard pattern.
+Valid include guard patterns use capital letters, start with the repository name, include the path to the file and the file name itself, have directory separators and hyphens replaced with underscores, and have a trailing underscore. The path to the file starts from the repository root by default. Other paths, such as include directories, can be specified in the group ``includeGuardRoots``. If a path matches, that string will be truncated from the include guard pattern.
+
+For example, given a file at `allwpilib/src/main/native/include/wpiutil/support/ConcurrentQueue.h` and an include path of `src/main/native/include/`, the resulting include guard would be `ALLWPILIB_WPIUTIL_SUPPORT_CONCURRENTQUEUE_H_`.
 
 The group ``repoRootNameOverride`` allows one to override the repository name used in include guards. This is useful for giving subprojects within one repository different repository roots in their include guards. Only specify one name in this group because subsequent names will be ignored.
 

wpiformat/test/test_includeguard.py

@@ -66,4 +66,17 @@ def test_includeguard():
         os.linesep + \
         "#endif  // STYLEGUIDE_TEST_H_" + os.linesep, True, True)
 
+    # Ensure leading underscores are removed (this occurs if the user doesn't
+    # include a trailing "/" in the include guard root)
+    test.add_input("./Test/Test.h",
+        "#ifndef STYLEGUIDE_WPIFORMAT_TEST_TEST_H_" + os.linesep + \
+        "#define STYLEGUIDE_WPIFORMAT_TEST_TEST_H_" + os.linesep + \
+        os.linesep + \
+        "#endif  // STYLEGUIDE_WPIFORMAT_TEST_TEST_H_" + os.linesep)
+    test.add_output(
+        "#ifndef STYLEGUIDE_TEST_H_" + os.linesep + \
+        "#define STYLEGUIDE_TEST_H_" + os.linesep + \
+        os.linesep + \
+        "#endif  // STYLEGUIDE_TEST_H_" + os.linesep, True, True)
+
     test.run(OutputType.FILE)

wpiformat/wpiformat/includeguard.py

@@ -90,11 +90,14 @@ def make_include_guard(self, config_file, name):
         include_roots = config_file.group("includeGuardRoots")
 
         if include_roots:
+            prefix = ""
             for include_root in include_roots:
-                if guard_root.startswith(include_root):
-                    guard_path += guard_root[len(include_root):]
-                    return regex.sub("[^a-zA-Z0-9]", "_",
-                                     guard_path).upper() + "_"
+                if guard_root.startswith(
+                        include_root) and len(include_root) > len(prefix):
+                    prefix = include_root
+            guard_path += guard_root[len(prefix):]
+            return (regex.sub("[^a-zA-Z0-9]", "_", guard_path).upper() +
+                    "_").lstrip("_")
 
         # No include guard roots matched, so append full name
         guard_path += guard_root