adding custom citations to markdown generator

verilog/analysis/verilog_linter.cc

@@ -375,6 +375,8 @@ void GetLintRuleDescriptionsHelpFlag(std::ostream* os,
     for (const auto& [rule_id, citation] : citations) {
       auto rule = rule_map.find(rule_id);
       if (rule != rule_map.end()) {
+        // we can move here, cause process
+        // exits after this function
         rule->second.description = std::move(citation);
       }
     }
@@ -399,12 +401,24 @@ void GetLintRuleDescriptionsHelpFlag(std::ostream* os,
   }
 }
 
-void GetLintRuleDescriptionsMarkdown(std::ostream* os) {
+void GetLintRuleDescriptionsMarkdown(std::ostream* os,
+                                     const CustomCitationMap& citations) {
   auto rule_map = analysis::GetAllRuleDescriptionsMarkdown();
   for (const auto& rule_id : analysis::kDefaultRuleSet) {
     rule_map[rule_id].default_enabled = true;
   }
 
+  if (!citations.empty()) {
+    for (const auto& [rule_id, citation] : citations) {
+      auto rule = rule_map.find(rule_id);
+      if (rule != rule_map.end()) {
+        // we can move here, cause process
+        // exits after this function
+        rule->second.description = std::move(citation);
+      }
+    }
+  }
+
   for (const auto& rule : rule_map) {
     // Print the rule, description and if it is enabled by default.
     *os << "### " << rule.first << "\n";

verilog/analysis/verilog_linter.h

@@ -133,7 +133,9 @@ void GetLintRuleDescriptionsHelpFlag(std::ostream*, absl::string_view,
                                      const CustomCitationMap&);
 
 // Outputs the descriptions for every rule, formatted for markdown.
-void GetLintRuleDescriptionsMarkdown(std::ostream*);
+// When custom citations are delivered substitute chosen rule description
+// with citations specified by user
+void GetLintRuleDescriptionsMarkdown(std::ostream*, const CustomCitationMap&);
 
 // Parse the file with custom citations
 CustomCitationMap ParseCitations(absl::string_view);

verilog/analysis/verilog_linter_test.cc

@@ -425,13 +425,27 @@ TEST(VerilogLinterDocumentationTest,
 
 TEST(VerilogLinterDocumentationTest, AllRulesMarkdown) {
   std::ostringstream stream;
-  verilog::GetLintRuleDescriptionsMarkdown(&stream);
+  verilog::GetLintRuleDescriptionsMarkdown(&stream, {});
   // Spot-check a few patterns, must mostly make sure generation
   // works without any fatal errors.
   EXPECT_TRUE(absl::StrContains(stream.str(), "line-length"));
   EXPECT_TRUE(absl::StrContains(stream.str(), "posix-eof"));
   EXPECT_TRUE(absl::StrContains(stream.str(), "Enabled by default:"));
 }
 
+TEST(VerilogLinterDocumentationTest, AllRulesMarkdownWithCustomCitations) {
+  std::ostringstream stream;
+  verilog::CustomCitationMap citations = {
+      {"struct-union-name-style", "one line citation is ok"},
+      {"signal-name-style", "multi line citation\nis also\ncorrect"}};
+
+  verilog::GetLintRuleDescriptionsMarkdown(&stream, citations);
+  // Spot-check a few patterns, must mostly make sure generation
+  // works without any fatal errors.
+  EXPECT_TRUE(absl::StrContains(stream.str(), "one line citation is ok"));
+  EXPECT_TRUE(absl::StrContains(stream.str(), "is also\ncorrect"));
+  EXPECT_TRUE(absl::StrContains(stream.str(), "Enabled by default:"));
+}
+
 }  // namespace
 }  // namespace verilog

verilog/tools/lint/verilog_lint.cc

@@ -69,25 +69,26 @@ int main(int argc, char** argv) {
       absl::StrCat("usage: ", argv[0], " [options] <file> [<file>...]");
   const auto args = verible::InitCommandLine(usage, &argc, &argv);
 
-  std::string help_flag = absl::GetFlag(FLAGS_help_rules);
   std::string custom_citations_file = absl::GetFlag(FLAGS_lint_rule_citations);
+  std::string content;
   CustomCitationMap citations;
+  if (!custom_citations_file.empty()) {
+    const absl::Status config_read_status =
+        verible::file::GetContents(custom_citations_file, &content);
+    if (!config_read_status.ok()) return -1;
+    citations = verilog::ParseCitations(content);
+  }
+
+  std::string help_flag = absl::GetFlag(FLAGS_help_rules);
   if (!help_flag.empty()) {
-    std::string content;
-    if (!custom_citations_file.empty()) {
-      const absl::Status config_read_status =
-          verible::file::GetContents(custom_citations_file, &content);
-      if (!config_read_status.ok()) return -1;
-      citations = verilog::ParseCitations(content);
-    }
     verilog::GetLintRuleDescriptionsHelpFlag(&std::cout, help_flag, citations);
     return 0;
   }
 
   // In documentation generation mode, print documentation and exit immediately.
   bool generate_markdown_flag = absl::GetFlag(FLAGS_generate_markdown);
   if (generate_markdown_flag) {
-    verilog::GetLintRuleDescriptionsMarkdown(&std::cout);
+    verilog::GetLintRuleDescriptionsMarkdown(&std::cout, citations);
     return 0;
   }