Merge pull request #906 from veryl-lang/refine_doc

Refine document generation

crates/veryl/src/cmd_doc.rs

@@ -1,11 +1,11 @@
-use crate::doc::DocBuilder;
+use crate::doc::{DocBuilder, TopLevelItem};
 use crate::OptDoc;
 use log::info;
 use miette::{IntoDiagnostic, Result, WrapErr};
 use std::collections::BTreeMap;
 use std::fs;
-use veryl_analyzer::symbol::SymbolKind;
-use veryl_analyzer::Analyzer;
+use veryl_analyzer::symbol::{SymbolId, SymbolKind};
+use veryl_analyzer::{symbol_table, Analyzer};
 use veryl_metadata::Metadata;
 use veryl_parser::resource_table;
 use veryl_parser::Parser;
@@ -51,25 +51,63 @@ impl CmdDoc {
 
         for symbol in veryl_analyzer::symbol_table::get_all() {
             let text = resource_table::get_str_value(symbol.token.text).unwrap();
+            let file_name = text.clone();
+            let symbol = symbol.clone();
             if format!("{}", symbol.namespace) == metadata.project.name && symbol.public {
-                match symbol.kind {
-                    SymbolKind::Module(_) => {
-                        modules.insert(text, symbol.clone());
+                match &symbol.kind {
+                    SymbolKind::Module(x) => {
+                        let html_name = fmt_generic_parameters(&text, &x.generic_parameters);
+                        let item = TopLevelItem {
+                            file_name,
+                            html_name,
+                            symbol,
+                        };
+                        modules.insert(text, item);
                     }
-                    SymbolKind::Interface(_) => {
-                        interfaces.insert(text, symbol.clone());
+                    SymbolKind::Interface(x) => {
+                        let html_name = fmt_generic_parameters(&text, &x.generic_parameters);
+                        let item = TopLevelItem {
+                            file_name,
+                            html_name,
+                            symbol,
+                        };
+                        interfaces.insert(text, item);
                     }
-                    SymbolKind::Package(_) => {
-                        packages.insert(text, symbol.clone());
+                    SymbolKind::Package(x) => {
+                        let html_name = fmt_generic_parameters(&text, &x.generic_parameters);
+                        let item = TopLevelItem {
+                            file_name,
+                            html_name,
+                            symbol,
+                        };
+                        packages.insert(text, item);
                     }
                     _ => (),
                 }
             }
         }
 
+        let modules: Vec<_> = modules.into_values().collect();
+        let interfaces: Vec<_> = interfaces.into_values().collect();
+        let packages: Vec<_> = packages.into_values().collect();
+
         let builder = DocBuilder::new(metadata, modules, interfaces, packages)?;
         builder.build()?;
 
         Ok(true)
     }
 }
+
+fn fmt_generic_parameters(name: &str, params: &[SymbolId]) -> String {
+    if params.is_empty() {
+        name.to_string()
+    } else {
+        let mut name = name.to_string();
+        name.push_str("::&lt;");
+        for param in params {
+            let symbol = symbol_table::get(*param).unwrap();
+            name.push_str(&format!("{}, ", symbol.token.text));
+        }
+        format!("{}&gt;", name.strip_suffix(", ").unwrap())
+    }
+}

crates/veryl/src/doc/doc_builder.rs

@@ -3,7 +3,7 @@ use handlebars::Handlebars;
 use mdbook::{Config, MDBook};
 use miette::{IntoDiagnostic, Result};
 use serde::Serialize;
-use std::collections::{BTreeMap, HashSet};
+use std::collections::HashSet;
 use std::fs::{self, File};
 use std::io::Write;
 use std::path::PathBuf;
@@ -24,27 +24,27 @@ const SUMMARY_TMPL: &str = r###"
 
 - [Modules](modules.md)
   {{#each modules}}
-  - [{{this}}]({{this}}.md)
+  - [{{this.0}}]({{this.1}}.md)
   {{/each}}
 
 - [Interfaces](interfaces.md)
   {{#each interfaces}}
-  - [{{this}}]({{this}}.md)
+  - [{{this.0}}]({{this.1}}.md)
   {{/each}}
 
 - [Packages](packages.md)
   {{#each packages}}
-  - [{{this}}]({{this}}.md)
+  - [{{this.0}}]({{this.1}}.md)
   {{/each}}
 "###;
 
 #[derive(Serialize)]
 struct SummaryData {
     name: String,
     version: String,
-    modules: Vec<String>,
-    interfaces: Vec<String>,
-    packages: Vec<String>,
+    modules: Vec<(String, String)>,
+    interfaces: Vec<(String, String)>,
+    packages: Vec<(String, String)>,
 }
 
 const INDEX_TMPL: &str = r###"
@@ -164,7 +164,11 @@ const MODULE_TMPL: &str = r#"
 {{#each ports}}
 <tr>
     <th class="table_list_item">{{this.name}}</th>
-    <td class="table_list_item"><span class="hljs-keyword">{{this.direction}}</span> <span class="hljs-attribute">{{this.clock_domain}}</span> <span class="hljs-type">{{this.typ}}</span></td>
+    <td class="table_list_item"><span class="hljs-keyword">{{this.direction}}</span></td>
+    {{#if ../clock_domains}}
+    <td class="table_list_item"><span class="hljs-attribute">{{this.clock_domain}}</span></td>
+    {{/if}}
+    <td class="table_list_item"><span class="hljs-type">{{this.typ}}</span></td>
     <td class="table_list_item">{{this.description}}</td>
 </tr>
 {{/each}}
@@ -248,17 +252,24 @@ pub struct DocBuilder {
     root_dir: PathBuf,
     src_dir: PathBuf,
     theme_dir: PathBuf,
-    modules: BTreeMap<String, Symbol>,
-    interfaces: BTreeMap<String, Symbol>,
-    packages: BTreeMap<String, Symbol>,
+    modules: Vec<TopLevelItem>,
+    interfaces: Vec<TopLevelItem>,
+    packages: Vec<TopLevelItem>,
+}
+
+#[derive(Clone)]
+pub struct TopLevelItem {
+    pub file_name: String,
+    pub html_name: String,
+    pub symbol: Symbol,
 }
 
 impl DocBuilder {
     pub fn new(
         metadata: &Metadata,
-        modules: BTreeMap<String, Symbol>,
-        interfaces: BTreeMap<String, Symbol>,
-        packages: BTreeMap<String, Symbol>,
+        modules: Vec<TopLevelItem>,
+        interfaces: Vec<TopLevelItem>,
+        packages: Vec<TopLevelItem>,
     ) -> Result<Self> {
         let temp_dir = tempfile::tempdir().into_diagnostic()?;
         let root_dir = temp_dir.path().to_path_buf();
@@ -288,19 +299,19 @@ impl DocBuilder {
         self.build_component("interfaces.md", self.build_interfaces())?;
         self.build_component("packages.md", self.build_packages())?;
 
-        for (k, v) in &self.modules {
-            let file = format!("{}.md", k);
-            self.build_component(&file, self.build_module(k, v))?;
+        for x in &self.modules {
+            let file = format!("{}.md", x.file_name);
+            self.build_component(&file, self.build_module(&x.html_name, &x.symbol))?;
         }
 
-        for (k, v) in &self.interfaces {
-            let file = format!("{}.md", k);
-            self.build_component(&file, self.build_interface(k, v))?;
+        for x in &self.interfaces {
+            let file = format!("{}.md", x.file_name);
+            self.build_component(&file, self.build_interface(&x.html_name, &x.symbol))?;
         }
 
-        for (k, v) in &self.packages {
-            let file = format!("{}.md", k);
-            self.build_component(&file, self.build_package(k, v))?;
+        for x in &self.packages {
+            let file = format!("{}.md", x.file_name);
+            self.build_component(&file, self.build_package(&x.html_name, &x.symbol))?;
         }
 
         let mut cfg = Config::default();
@@ -388,9 +399,24 @@ impl DocBuilder {
     }
 
     fn build_summary(&self) -> String {
-        let modules: Vec<_> = self.modules.keys().cloned().collect();
-        let interfaces: Vec<_> = self.interfaces.keys().cloned().collect();
-        let packages: Vec<_> = self.packages.keys().cloned().collect();
+        let modules: Vec<_> = self
+            .modules
+            .iter()
+            .cloned()
+            .map(|x| (x.html_name, x.file_name))
+            .collect();
+        let interfaces: Vec<_> = self
+            .interfaces
+            .iter()
+            .cloned()
+            .map(|x| (x.html_name, x.file_name))
+            .collect();
+        let packages: Vec<_> = self
+            .packages
+            .iter()
+            .cloned()
+            .map(|x| (x.html_name, x.file_name))
+            .collect();
         let data = SummaryData {
             name: self.metadata.project.name.clone(),
             version: format!("{}", self.metadata.project.version),
@@ -422,9 +448,9 @@ impl DocBuilder {
         let items: Vec<_> = self
             .modules
             .iter()
-            .map(|(k, v)| ListItem {
-                name: k.clone(),
-                description: v.doc_comment.format(true),
+            .map(|x| ListItem {
+                name: x.html_name.clone(),
+                description: x.symbol.doc_comment.format(true),
             })
             .collect();
 
@@ -442,9 +468,9 @@ impl DocBuilder {
         let items: Vec<_> = self
             .interfaces
             .iter()
-            .map(|(k, v)| ListItem {
-                name: k.clone(),
-                description: v.doc_comment.format(true),
+            .map(|x| ListItem {
+                name: x.html_name.clone(),
+                description: x.symbol.doc_comment.format(true),
             })
             .collect();
 
@@ -462,9 +488,9 @@ impl DocBuilder {
         let items: Vec<_> = self
             .packages
             .iter()
-            .map(|(k, v)| ListItem {
-                name: k.clone(),
-                description: v.doc_comment.format(true),
+            .map(|x| ListItem {
+                name: x.html_name.clone(),
+                description: x.symbol.doc_comment.format(true),
             })
             .collect();
 

testcases/sv/55_generic_module.sv

@@ -7,6 +7,7 @@ module veryl_testcase_Module55;
     veryl_testcase___Module55F__Module55B u5 ();
 endmodule
 
+/// Generic module test for doc comment
 module veryl_testcase___Module55A__Module55B;
     veryl_testcase_Module55B u ();
 endmodule

testcases/sv/56_generic_interface.sv

@@ -5,13 +5,17 @@ module veryl_testcase_Module56;
     veryl_testcase___Interface56B__Package56B u3 ();
 endmodule
 
+/// Generic interface test for doc comment
 interface veryl_testcase___Interface56A__Package56A;
     logic [veryl_testcase_Package56A::X-1:0] _a;
 endinterface
+
+/// Generic interface test for doc comment
 interface veryl_testcase___Interface56A__Package56B;
     logic [veryl_testcase_Package56B::X-1:0] _a;
 endinterface
 
+/// Generic interface test for doc comment
 interface veryl_testcase___Interface56B__Package56A;
     logic [veryl_testcase_Package56A::X-1:0] _b;
 endinterface

testcases/sv/57_generic_package.sv

@@ -8,13 +8,17 @@ module veryl_testcase_Module57;
     always_comb _e.c = 1;
 endmodule
 
+/// Generic package test for doc comment
 package veryl_testcase___Package57A__1;
     localparam int unsigned X = 1;
 endpackage
+
+/// Generic package test for doc comment
 package veryl_testcase___Package57A__2;
     localparam int unsigned X = 2;
 endpackage
 
+/// Generic package test for doc comment
 package veryl_testcase___Package57B__3;
     localparam int unsigned X = 3;
 endpackage

testcases/veryl/55_generic_module.veryl

@@ -7,7 +7,8 @@ module Module55 {
     inst u5: Module55F::<>;
 }
 
-module Module55A::<T> {
+/// Generic module test for doc comment
+pub module Module55A::<T> {
     inst u: T;
 }
 

testcases/veryl/56_generic_interface.veryl

@@ -5,11 +5,13 @@ module Module56 {
     inst u3: Interface56B::<>;
 }
 
-interface Interface56A::<T> {
+/// Generic interface test for doc comment
+pub interface Interface56A::<T> {
     var _a: logic<T::X>;
 }
 
-interface Interface56B::<T = Package56B> {
+/// Generic interface test for doc comment
+pub interface Interface56B::<T = Package56B> {
     var _b: logic<T::X>;
 }
 

testcases/veryl/57_generic_package.veryl

@@ -8,11 +8,13 @@ module Module57 {
     assign _e.c = 1;
 }
 
-package Package57A::<T> {
+/// Generic package test for doc comment
+pub package Package57A::<T> {
     local X: u32 = T;
 }
 
-package Package57B::<T = 4> {
+/// Generic package test for doc comment
+pub package Package57B::<T = 4> {
     local X: u32 = T;
 }