Add command line options to control which macros to include in the ge…

…nerated docs And add tests for macro generation and capture prefixes
chromium · Dec 10, 2023 · ecd377a · ecd377a
1 parent bb1589b
commit ecd377a
Show file tree

Hide file tree

Showing 14 changed files with 246 additions and 8 deletions.
diff --git a/.github/workflows/subdoc.yml b/.github/workflows/subdoc.yml
@@ -156,6 +156,8 @@ jobs:
             --exclude-file-pattern /third_party/ \
             --exclude-file-pattern /test/ \
             --exclude-file-pattern test.cc \
+            --include-macro-prefix sus_ \
+            --include-macro-prefix SUS_ \
             --copy-file subdoc/gen_tests/subdoc-test-style.css \
             --copy-file web/logo.png \
             --copy-file web/logo32.png \

diff --git a/.github/workflows/try.yml b/.github/workflows/try.yml
@@ -404,6 +404,8 @@ jobs:
             --exclude-file-pattern /third_party/ \
             --exclude-file-pattern /test/ \
             --exclude-file-pattern test.cc \
+            --include-macro-prefix sus_ \
+            --include-macro-prefix SUS_ \
             --copy-file subdoc/gen_tests/subdoc-test-style.css \
             --copy-file web/logo.png \
             --copy-file web/logo32.png \

diff --git a/subdoc/README.md b/subdoc/README.md
@@ -83,7 +83,7 @@ void secret() {}
 
 ```
 subdoc --project-name NAME [--include-file-pattern PATH] [--exclude-file-pattern PATH]
-    [--css PATH] [--copy-file PATH] [--project-md PATH]
+    [--include-macro-prefix PREFIX] [--css PATH] [--copy-file PATH] [--project-md PATH]
     FILES...
 ```
 
@@ -113,6 +113,13 @@ Symbols defined in files whose path contains the `PATH` as a substring are
 excluded. This overrides symbols that would have been included by
 `--include-file-pattern`.
 
+```
+--include-macro-prefix PREFIX
+```
+Macros are only included in the generated docs if they match a prefix specified
+by this flag. It can be given more than once to name multiple prefixes to match
+against.
+
 By default Subdoc also excludes symbols in a namespace named `__private` or
 `test`, or any namespace nested within one.
 TODO: Make this a command line flag.

diff --git a/subdoc/gen_tests/struct-complex/index.html b/subdoc/gen_tests/struct-complex/index.html
@@ -55,6 +55,15 @@
         <li>
           <a class="sidebar-item" href="S.html">S</a>
         </li>
+        <li>
+          <a class="sidebar-header" href="#macros">Macros</a>
+        </li>
+        <li>
+          <a class="sidebar-item" href="macro.sus_macro_for_test.html">sus_macro_for_test</a>
+        </li>
+        <li>
+          <a class="sidebar-item" href="macro.sus_macro_for_test_fn.html">sus_macro_for_test_fn</a>
+        </li>
       </ul>
     </div>
   </nav>
@@ -96,6 +105,33 @@
           </li>
         </ul>
       </div>
+      <div class="section macros">
+        <div class="section-header">
+          <a name="macros" href="#macros">Macros</a>
+        </div>
+        <ul class="section-items item-table">
+          <li class="section-item">
+            <div class="overload-set item-name">
+              <div class="overload">
+                <div class="macro-signature"> <a class="macro-name" href="macro.sus_macro_for_test.html">sus_macro_for_test</a></div>
+              </div>
+            </div>
+            <div class="description short">
+              <p>Comment headline on sus_macro_for_test.</p>
+            </div>
+          </li>
+          <li class="section-item">
+            <div class="overload-set item-name">
+              <div class="overload">
+                <div class="macro-signature"> <a class="macro-name" href="macro.sus_macro_for_test_fn.html">sus_macro_for_test_fn</a></div>
+              </div>
+            </div>
+            <div class="description short">
+              <p>Comment headline on sus_macro_for_test_fn.</p>
+            </div>
+          </li>
+        </ul>
+      </div>
     </div>
   </main>
 </body>
diff --git a/subdoc/gen_tests/struct-complex/macro.sus_macro_for_test.html b/subdoc/gen_tests/struct-complex/macro.sus_macro_for_test.html
@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+
+<head>
+  <meta name="generator" content="subdoc"></meta>
+  <meta name="viewport" content="width=device-width, initial-scale=1"></meta>
+  <meta property="og:type" content="website"></meta>
+  <meta property="og:site_name" content="PROJECT NAME"></meta>
+  <title>sus_macro_for_test - PROJECT NAME</title>
+  <meta property="og:title" content="sus_macro_for_test - PROJECT NAME"></meta>
+  <meta name="description" content="Comment headline on sus_macro_for_test."></meta>
+  <meta property="og:description" content="Comment headline on sus_macro_for_test."></meta>
+  <link rel="stylesheet" href="../subdoc-test-style.css">
+  <link rel="icon" type="image/svg+xml" href="../icon.svg">
+  <link rel="alternate icon" type="image/png" href="../icon.png">
+  <meta property="og:image" content="../icon.svg"></meta>
+</head>
+
+<body>
+  <nav class="topbar">
+    <button class="sidebar-menu-button" onclick="let e = document.getElementsByClassName('sidebar')[0];e.classList.toggle('shown');">
+      ☰
+    </button>
+    <a class="topbar-logo-link" href="index.html"><div class="topbar-logo-border">
+        <img class="topbar-logo" src="PROJECT LOGO.png"></img>
+      </div></a>
+    <span class="topbar-text-area">
+      <span class="topbar-title">
+        <a href="#">sus_macro_for_test</a>
+      </span>
+    </span>
+  </nav>
+  <nav class="sidebar">
+    <a class="sidebar-logo-link" href="index.html"><div class="sidebar-logo-border">
+        <img class="sidebar-logo" src="PROJECT LOGO.png"></img>
+      </div></a>
+    <div class="sidebar-pretitle sidebar-text">
+      macro
+    </div>
+    <div class="sidebar-title sidebar-text">
+      <a href="#">sus_macro_for_test</a>
+    </div>
+    <div class="sidebar-subtitle sidebar-text">
+    </div>
+    <div class="sidebar-links sidebar-text">
+      <ul>
+      </ul>
+    </div>
+  </nav>
+  <main>
+    <div class="macro">
+      <div class="section overview">
+        <div class="section-header">
+          <span>
+            Macro
+          </span>
+          <a class="project-name" href="index.html">PROJECT NAME</a>
+          <span class="namespace-dots">::</span>
+          <a class="macro-name" href="#">sus_macro_for_test</a>
+        </div>
+        <div class="overload-set">
+          <div class="overload">
+            <div class="macro-signature"><span class="macro-define">#define</span> <a class="macro-name" href="#">sus_macro_for_test</a></div>
+          </div>
+        </div>
+        <div class="description long">
+          <p>Comment headline on sus_macro_for_test.</p>
+<p>Also refers to <a href="macro.sus_macro_for_test_fn.html">the other</a></p>
+
+        </div>
+      </div>
+    </div>
+  </main>
+</body>
diff --git a/subdoc/gen_tests/struct-complex/macro.sus_macro_for_test_fn.html b/subdoc/gen_tests/struct-complex/macro.sus_macro_for_test_fn.html
@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+
+<head>
+  <meta name="generator" content="subdoc"></meta>
+  <meta name="viewport" content="width=device-width, initial-scale=1"></meta>
+  <meta property="og:type" content="website"></meta>
+  <meta property="og:site_name" content="PROJECT NAME"></meta>
+  <title>sus_macro_for_test_fn - PROJECT NAME</title>
+  <meta property="og:title" content="sus_macro_for_test_fn - PROJECT NAME"></meta>
+  <meta name="description" content="Comment headline on sus_macro_for_test_fn."></meta>
+  <meta property="og:description" content="Comment headline on sus_macro_for_test_fn."></meta>
+  <link rel="stylesheet" href="../subdoc-test-style.css">
+  <link rel="icon" type="image/svg+xml" href="../icon.svg">
+  <link rel="alternate icon" type="image/png" href="../icon.png">
+  <meta property="og:image" content="../icon.svg"></meta>
+</head>
+
+<body>
+  <nav class="topbar">
+    <button class="sidebar-menu-button" onclick="let e = document.getElementsByClassName('sidebar')[0];e.classList.toggle('shown');">
+      ☰
+    </button>
+    <a class="topbar-logo-link" href="index.html"><div class="topbar-logo-border">
+        <img class="topbar-logo" src="PROJECT LOGO.png"></img>
+      </div></a>
+    <span class="topbar-text-area">
+      <span class="topbar-title">
+        <a href="#">sus_macro_for_test_fn</a>
+      </span>
+    </span>
+  </nav>
+  <nav class="sidebar">
+    <a class="sidebar-logo-link" href="index.html"><div class="sidebar-logo-border">
+        <img class="sidebar-logo" src="PROJECT LOGO.png"></img>
+      </div></a>
+    <div class="sidebar-pretitle sidebar-text">
+      macro
+    </div>
+    <div class="sidebar-title sidebar-text">
+      <a href="#">sus_macro_for_test_fn</a>
+    </div>
+    <div class="sidebar-subtitle sidebar-text">
+    </div>
+    <div class="sidebar-links sidebar-text">
+      <ul>
+      </ul>
+    </div>
+  </nav>
+  <main>
+    <div class="macro">
+      <div class="section overview">
+        <div class="section-header">
+          <span>
+            Macro
+          </span>
+          <a class="project-name" href="index.html">PROJECT NAME</a>
+          <span class="namespace-dots">::</span>
+          <a class="macro-name" href="#">sus_macro_for_test_fn</a>
+        </div>
+        <div class="overload-set">
+          <div class="overload">
+            <div class="macro-signature"><span class="macro-define">#define</span> <a class="macro-name" href="#">sus_macro_for_test_fn</a>(a, b, c, ...)</div>
+          </div>
+        </div>
+        <div class="description long">
+          <p>Comment headline on sus_macro_for_test_fn.</p>
+<p>Also refers to <a href="macro.sus_macro_for_test.html">the other</a></p>
+
+        </div>
+      </div>
+    </div>
+  </main>
+</body>
diff --git a/subdoc/gen_tests/struct-complex/test.cc b/subdoc/gen_tests/struct-complex/test.cc
@@ -1,6 +1,18 @@
 // This tests static and non-static members. They are intermixed and will
 // come out grouped and in alphabetical order.
 
+/// Comment headline on sus_macro_for_test_fn.
+///
+/// Also refers to [the other]($sus_macro_for_test)
+#define sus_macro_for_test_fn(a, b, c, ...)
+/// Comment headline on sus_macro_for_test.
+///
+/// Also refers to [the other]($sus_macro_for_test_fn)
+#define sus_macro_for_test
+
+/// A private macro which is not in the docs.
+#define _sus_macro_for_test
+
 struct OtherType {};
 
 namespace __private { struct Private {}; }

diff --git a/subdoc/lib/run_options.h b/subdoc/lib/run_options.h
@@ -45,13 +45,19 @@ struct RunOptions {
     on_tu_complete = sus::some(sus::move(fn));
     return sus::move(*this);
   }
+  RunOptions set_macro_prefixes(sus::Vec<std::string> prefixes) && {
+    macro_prefixes = sus::move(prefixes);
+    return sus::move(*this);
+  }
 
   /// Whether to print progress while collecting documentation from souce files.
   bool show_progress = true;
   /// Defaults to match everything.
   std::regex include_path_patterns = std::regex("");
   /// Defaults to match nothing.
   std::regex exclude_path_patterns;
+  /// Prefixes of macros to be included in docs.
+  sus::Vec<std::string> macro_prefixes;
   /// A closure to run after parsing each translation unit.
   ///
   /// Used for tests to observe the AST and test subdoc methods that act on

diff --git a/subdoc/lib/visit.cc b/subdoc/lib/visit.cc
@@ -190,8 +190,10 @@ class Visitor : public clang::RecursiveASTVisitor<Visitor> {
     for (auto& [identifier_info, macro_state] : preprocessor_.macros()) {
       auto name = std::string(identifier_info->getName());
 
-      // TODO: Filter by name properly.
-      if (!name.starts_with("sus_") && !name.starts_with("SUS_")) continue;
+      if (!cx_.options.macro_prefixes.iter().any(
+              [&](const auto& prefix) { return name.starts_with(prefix); })) {
+        continue;
+      }
 
       // Get all comments in the file the macro definition was from.
       clang::MacroDefinition defn =

diff --git a/subdoc/subdoc_main.cc b/subdoc/subdoc_main.cc
@@ -98,6 +98,14 @@ int main(int argc, const char** argv) {
           "patterns."),
       llvm::cl::cat(option_category));
 
+  llvm::cl::list<std::string> option_include_macro_prefixes(
+      "include-macro-prefix",
+      llvm::cl::desc(
+          "Macros are only included in the generated output if they match a "
+          "prefix specified by --include-macro-prefix. May be specified "
+          "multiple times for multiple prefixes."),
+      llvm::cl::cat(option_category));
+
   llvm::cl::opt<bool> option_ignore_bad_code_links(
       "ignore-bad-code-links",
       llvm::cl::desc("Ignore bad code links, don't generate an error. Useful "
@@ -196,6 +204,10 @@ int main(int argc, const char** argv) {
       run_options.project_overview_text = sus::move(stream).str();
     }
   }
+  run_options.macro_prefixes =
+      sus::iter::from_range(option_include_macro_prefixes)
+          .cloned()
+          .collect<sus::Vec<std::string>>();
 
   auto fs = llvm::vfs::getRealFileSystem();
   auto result = subdoc::run_files(comp_db, sus::move(run_against_files),

diff --git a/subdoc/tests/macros_unittest.cc b/subdoc/tests/macros_unittest.cc
@@ -147,16 +147,23 @@ TEST_F(SubDocTest, MacroUsedInExcludedFile) {
 #endif
 
 TEST_F(SubDocTest, Macro) {
-  auto result = run_code(R"(
+  const auto opts =
+      subdoc::RunOptions()           //
+          .set_show_progress(false)  //
+          .set_macro_prefixes(sus::Vec<std::string>("one_", "TWO_"));
+  auto result = run_code_with_options(opts, R"(
     /// Comment headline
-    #define f() 
+    #define one_f() 
     /// Comment headline 2
-    #  define g() 
+    #  define TWO_G() 
+    /// Comment headline 3
+    #  define ONE_G() 
 
-    void h() {}
+    void h() {}  // Without any code there's no AST to visit.
   )");
   ASSERT_TRUE(result.is_ok());
   subdoc::Database db = sus::move(result).unwrap();
   EXPECT_TRUE(has_macro_comment(db, "2:5", "<p>Comment headline</p>"));
   EXPECT_TRUE(has_macro_comment(db, "4:5", "<p>Comment headline 2</p>"));
+  EXPECT_TRUE(!has_macro_comment(db, "6:5", "<p>Comment headline 3</p>"));
 }
diff --git a/subdoc/tests/subdoc_gen_test.h b/subdoc/tests/subdoc_gen_test.h
@@ -43,7 +43,9 @@ class SubDocGenTest : public testing::Test {
     auto args = sus::Vec<std::string>();
     args.push(std::string(subdoc::tests::cpp_version_flag(cpp_version_)));
 
-    auto run_options = subdoc::RunOptions().set_show_progress(false);
+    auto run_options =
+        subdoc::RunOptions().set_show_progress(false).set_macro_prefixes(
+            sus::Vec<std::string>("sus_"));
 
     auto result = subdoc::run_test(sus::move(content), args.as_slice(),
                                    sus::move(run_options));

diff --git a/tools/run_subdoc.bat b/tools/run_subdoc.bat
@@ -3,6 +3,8 @@ out\subdoc\subdoc -p out --out docs ^
     --exclude-file-pattern /third_party/ ^
     --exclude-file-pattern /test/ ^
     --exclude-file-pattern test.cc ^
+    --include-macro-prefix sus_ ^
+    --include-macro-prefix SUS_ ^
     --css subdoc-test-style.css ^
     --copy-file subdoc/gen_tests/subdoc-test-style.css ^
     --copy-file web/logo.png ^

diff --git a/tools/run_subdoc.sh b/tools/run_subdoc.sh
@@ -5,6 +5,8 @@ out/subdoc/subdoc -p out --out docs \
     --exclude-file-pattern /third_party/ \
     --exclude-file-pattern /test/ \
     --exclude-file-pattern test.cc \
+    --include-macro-prefix sus_ \
+    --include-macro-prefix SUS_ \
     --css subdoc-test-style.css \
     --copy-file subdoc/gen_tests/subdoc-test-style.css \
     --copy-file web/logo.png \