feat: node references (#674)

Author: crowlKats

benches/doc_parser.rs

@@ -15,8 +15,9 @@ use deno_graph::CapturingModuleAnalyzer;
 use deno_graph::GraphKind;
 use deno_graph::ModuleGraph;
 use deno_graph::ModuleSpecifier;
+use indexmap::IndexMap;
 
-async fn parse_with_reexports() -> Vec<DocNode> {
+async fn parse() -> IndexMap<ModuleSpecifier, Vec<DocNode>> {
   let source = std::fs::read_to_string("./benches/fixtures/deno.d.ts").unwrap();
   let sources = vec![(
     "file:///test/fixtures/deno.d.ts",
@@ -41,16 +42,15 @@ async fn parse_with_reexports() -> Vec<DocNode> {
       },
     )
     .await;
-  DocParser::new(&graph, &analyzer, DocParserOptions::default())
+  DocParser::new(&graph, &analyzer, &[root], DocParserOptions::default())
     .unwrap()
-    .parse_with_reexports(&root)
+    .parse()
     .unwrap()
 }
 
 fn doc_parser(c: &mut Criterion) {
-  c.bench_function("parse_with_rexports large", |b| {
-    b.to_async(FuturesExecutor)
-      .iter_with_large_drop(parse_with_reexports)
+  c.bench_function("parse large", |b| {
+    b.to_async(FuturesExecutor).iter_with_large_drop(parse)
   });
 }
 

deno.json

@@ -4,7 +4,7 @@
     "test": "deno test -A",
     "tailwind": "deno run -A build_css.ts",
     "gen_html": "cargo run --example ddoc -- --name=gen_html --output generated_docs/ --html",
-    "debug": "deno task tailwind && deno task doc ./tests/testdata/multiple/*",
+    "debug": "deno task tailwind && deno task gen_html ./tests/testdata/multiple/[!_]*",
     "test:update": "UPDATE=1 cargo test --locked --all-targets && cargo insta test --accept"
   },
   "workspace": ["js"],

examples/ddoc/main.rs

@@ -3,10 +3,10 @@
 use clap::App;
 use clap::Arg;
 use deno_doc::find_nodes_by_name_recursively;
-use deno_doc::html::HrefResolver;
 use deno_doc::html::UrlResolveKind;
 use deno_doc::html::UsageComposer;
 use deno_doc::html::UsageComposerEntry;
+use deno_doc::html::{GenerateCtx, HrefResolver};
 use deno_doc::DocNodeKind;
 use deno_doc::DocParser;
 use deno_doc::DocParserOptions;
@@ -59,6 +59,7 @@ async fn run() -> anyhow::Result<()> {
         .requires_all(&["output"]),
     )
     .arg(Arg::with_name("name").long("name").takes_value(true))
+    .arg(Arg::with_name("json").long("json").conflicts_with("html"))
     .arg(
       Arg::with_name("main_entrypoint")
         .long("main_entrypoint")
@@ -75,6 +76,7 @@ async fn run() -> anyhow::Result<()> {
     .get_matches();
   let source_files = matches.values_of("source_files").unwrap();
   let html = matches.is_present("html");
+  let json = matches.is_present("json");
   let name = if html {
     matches.value_of("name").map(|name| name.to_string())
   } else {
@@ -120,23 +122,21 @@ async fn run() -> anyhow::Result<()> {
     )
     .await;
 
+  let mut source_files = source_files.clone();
+  source_files.sort();
+
   let parser = DocParser::new(
     &graph,
     &analyzer,
+    &source_files,
     DocParserOptions {
       diagnostics: false,
       private,
     },
   )?;
+  let doc_nodes_by_url = parser.parse()?;
 
   if html {
-    let mut source_files = source_files.clone();
-    source_files.sort();
-    let mut doc_nodes_by_url = IndexMap::with_capacity(source_files.len());
-    for source_file in source_files {
-      let nodes = parser.parse_with_reexports(&source_file)?;
-      doc_nodes_by_url.insert(source_file, nodes);
-    }
     generate_docs_directory(
       name,
       output_dir,
@@ -146,19 +146,22 @@ async fn run() -> anyhow::Result<()> {
     return Ok(());
   }
 
-  let mut doc_nodes = Vec::with_capacity(1024);
-  for source_file in source_files {
-    let nodes = parser.parse_with_reexports(&source_file)?;
-    doc_nodes.extend(nodes);
-  }
+  let mut doc_nodes =
+    parser.parse()?.into_values().flatten().collect::<Vec<_>>();
 
   doc_nodes.retain(|doc_node| doc_node.kind() != DocNodeKind::Import);
   if let Some(filter) = maybe_filter {
     doc_nodes = find_nodes_by_name_recursively(doc_nodes, filter);
   }
 
-  let result = DocPrinter::new(&doc_nodes, true, false);
-  println!("{}", result);
+  if json {
+    serde_json::to_writer_pretty(std::io::stdout(), &doc_nodes)?;
+    println!();
+  } else {
+    let result = DocPrinter::new(&doc_nodes, true, false);
+    println!("{}", result);
+  }
+
   Ok(())
 }
 
@@ -269,7 +272,8 @@ fn generate_docs_directory(
       )
     })),
   };
-  let html = deno_doc::html::generate(options, doc_nodes_by_url)?;
+  let ctx = GenerateCtx::create_basic(options, doc_nodes_by_url)?;
+  let html = deno_doc::html::generate(ctx)?;
 
   let path = &output_dir_resolved;
   let _ = std::fs::remove_dir_all(path);

js/allow_leak_test.ts

@@ -10,7 +10,7 @@ Deno.test({
   async fn() {
     await assertRejects(
       async () => {
-        await doc("https://deno.land/x/bad.ts");
+        await doc(["https://deno.land/x/bad.ts"]);
       },
       Error,
       `Module not found "https://deno.land/x/bad.ts".`,

js/mod.ts

@@ -70,21 +70,21 @@ export interface DocOptions {
  * ```ts
  * import { doc } from "https://deno.land/x/deno_doc/mod.ts";
  *
- * const entries = await doc("https://deno.land/std/fmt/colors.ts");
+ * const entries = await doc(["https://deno.land/std/fmt/colors.ts"]);
  *
  * for (const entry of entries) {
  *   console.log(`name: ${entry.name} kind: ${entry.kind}`);
  * }
  * ```
  *
- * @param specifier The URL string of the specifier to document
+ * @param specifiers List of the URL strings of the specifiers to document
  * @param options A set of options for generating the documentation
  * @returns A promise that resolves with an array of documentation nodes
  */
 export async function doc(
-  specifier: string,
+  specifiers: string[],
   options: DocOptions = {},
-): Promise<Array<DocNode>> {
+): Promise<Record<string, Array<DocNode>>> {
   const {
     load = createCache().load,
     includeAll = false,
@@ -95,7 +95,7 @@ export async function doc(
 
   const wasm = await instantiate();
   return wasm.doc(
-    specifier,
+    specifiers,
     includeAll,
     (specifier: string, options: {
       isDynamic: boolean;

js/test.ts

@@ -6,9 +6,10 @@ import { doc, generateHtml } from "./mod.ts";
 Deno.test({
   name: "doc()",
   async fn() {
-    const entries = await doc(
-      "https://deno.land/std@0.104.0/fmt/colors.ts",
+    const records = await doc(
+      ["https://deno.land/std@0.104.0/fmt/colors.ts"],
     );
+    const entries = Object.values(records)[0];
     assertEquals(entries.length, 49);
     const fnStripColor = entries.find((n) =>
       n.kind === "function" && n.name === "stripColor"
@@ -32,8 +33,8 @@ Deno.test({
 Deno.test({
   name: "doc() - timings",
   async fn() {
-    const fixture = new URL("../benches/fixtures/deno.d.ts", import.meta.url)
-      .toString();
+    const fixture = [new URL("../benches/fixtures/deno.d.ts", import.meta.url)
+      .toString()];
 
     const start = Date.now();
     await doc(fixture);
@@ -58,7 +59,7 @@ Deno.test({
 Deno.test({
   name: "doc() - with headers",
   async fn() {
-    const entries = await doc("https://example.com/a", {
+    const entries = await doc(["https://example.com/a"], {
       load(specifier) {
         return Promise.resolve({
           kind: "module",
@@ -72,7 +73,7 @@ Deno.test({
         });
       },
     });
-    assertEquals(entries.length, 1);
+    assertEquals(Object.values(entries)[0].length, 1);
   },
 });
 
@@ -81,7 +82,7 @@ Deno.test({
   async fn() {
     await assertRejects(
       async () => {
-        await doc("./bad.ts");
+        await doc(["./bad.ts"]);
       },
       Error,
       "relative URL without a base",
@@ -92,7 +93,7 @@ Deno.test({
 Deno.test({
   name: "doc() - with import map",
   async fn() {
-    const entries = await doc("https://example.com/a.ts", {
+    const records = await doc(["https://example.com/a.ts"], {
       importMap: "https://example.com/import_map.json",
       load(specifier) {
         let content = "";
@@ -118,6 +119,7 @@ Deno.test({
         });
       },
     });
+    const entries = Object.values(records)[0];
     assertEquals(entries.length, 1);
     assertEquals(entries[0].kind, "class");
     assertEquals(entries[0].name, "B");
@@ -128,10 +130,12 @@ Deno.test({
   name: "generateHtml()",
   async fn() {
     const entries = await doc(
-      "https://deno.land/std@0.104.0/fmt/colors.ts",
+      ["https://deno.land/std@0.104.0/fmt/colors.ts"],
     );
 
-    const files = await generateHtml({ ["file:///colors.ts"]: entries }, {
+    const files = await generateHtml({
+      ["file:///colors.ts"]: Object.values(entries)[0],
+    }, {
       markdownRenderer(
         md,
         _titleOnly,

lib/lib.rs

@@ -148,7 +148,7 @@ impl Resolver for JsResolver {
 
 #[wasm_bindgen]
 pub async fn doc(
-  root_specifier: String,
+  root_specifiers: Vec<String>,
   include_all: bool,
   load: js_sys::Function,
   maybe_resolve: Option<js_sys::Function>,
@@ -157,7 +157,7 @@ pub async fn doc(
 ) -> anyhow::Result<JsValue, JsValue> {
   console_error_panic_hook::set_once();
   inner_doc(
-    root_specifier,
+    root_specifiers,
     include_all,
     load,
     maybe_resolve,
@@ -169,14 +169,17 @@ pub async fn doc(
 }
 
 async fn inner_doc(
-  root_specifier: String,
+  root_specifiers: Vec<String>,
   include_all: bool,
   load: js_sys::Function,
   maybe_resolve: Option<js_sys::Function>,
   maybe_import_map: Option<String>,
   print_import_map_diagnostics: bool,
 ) -> Result<JsValue, anyhow::Error> {
-  let root_specifier = ModuleSpecifier::parse(&root_specifier)?;
+  let root_specifiers = root_specifiers
+    .into_iter()
+    .map(|root_specifier| ModuleSpecifier::parse(&root_specifier))
+    .collect::<Result<Vec<_>, _>>()?;
   let mut loader = JsLoader::new(load);
   let maybe_resolver: Option<Box<dyn Resolver>> = if let Some(import_map) =
     maybe_import_map
@@ -232,7 +235,7 @@ async fn inner_doc(
   let mut graph = ModuleGraph::new(GraphKind::TypesOnly);
   graph
     .build(
-      vec![root_specifier.clone()],
+      root_specifiers.clone(),
       &mut loader,
       BuildOptions {
         module_analyzer: &analyzer,
@@ -244,12 +247,13 @@ async fn inner_doc(
   let entries = DocParser::new(
     &graph,
     &analyzer,
+    &root_specifiers,
     deno_doc::DocParserOptions {
       diagnostics: false,
       private: include_all,
     },
   )?
-  .parse_with_reexports(&root_specifier)?;
+  .parse()?;
   let serializer =
     serde_wasm_bindgen::Serializer::new().serialize_maps_as_objects(true);
   Ok(entries.serialize(&serializer).unwrap())
@@ -601,7 +605,7 @@ fn generate_html_inner(
       None
     };
 
-  let files = deno_doc::html::generate(
+  let ctx = deno_doc::html::GenerateCtx::create_basic(
     deno_doc::html::GenerateOptions {
       package_name,
       main_entrypoint,
@@ -627,6 +631,7 @@ fn generate_html_inner(
     },
     doc_nodes_by_url,
   )?;
+  let files = deno_doc::html::generate(ctx)?;
 
   let serializer =
     serde_wasm_bindgen::Serializer::new().serialize_maps_as_objects(true);

src/diagnostics.rs

@@ -403,7 +403,9 @@ impl<'a, 'b> DiagnosticDocNodeVisitor<'a, 'b> {
         | DocNodeKind::Namespace
         | DocNodeKind::TypeAlias
         | DocNodeKind::Variable => true,
-        DocNodeKind::Import | DocNodeKind::ModuleDoc => false,
+        DocNodeKind::Import
+        | DocNodeKind::ModuleDoc
+        | DocNodeKind::Reference => false,
       }
     }
 

src/html/jsdoc.rs

@@ -357,6 +357,7 @@ impl ModuleDocCtx {
 
     if !short_path.is_main {
       let partitions_by_kind = super::partition::partition_nodes_by_kind(
+        render_ctx.ctx,
         module_doc_nodes.iter().map(Cow::Borrowed),
         true,
       );