refactor: separate module doc from docnodes (#779)

Author: crowlKats

examples/ddoc/main.rs

@@ -210,22 +210,28 @@ async fn run() -> anyhow::Result<()> {
         return Ok(());
       }
 
-      let mut doc_nodes =
-        doc_nodes_by_url.into_values().flatten().collect::<Vec<_>>();
+      let mut merged_doc = deno_doc::Document::default();
+      for doc in doc_nodes_by_url.into_values() {
+        if merged_doc.module_doc.is_empty() {
+          merged_doc.module_doc = doc.module_doc;
+        }
+        merged_doc.symbols.extend(doc.symbols);
+      }
 
-      doc_nodes.retain(|doc_node| {
+      merged_doc.symbols.retain(|doc_node| {
         !matches!(doc_node.declarations[0].def, DeclarationDef::Import(..))
       });
 
       if let Some(filter) = filter {
-        doc_nodes = find_nodes_by_name_recursively(doc_nodes, &filter);
+        merged_doc.symbols =
+          find_nodes_by_name_recursively(merged_doc.symbols, &filter);
       }
 
       if json {
-        serde_json::to_writer_pretty(std::io::stdout(), &doc_nodes)?;
+        serde_json::to_writer_pretty(std::io::stdout(), &merged_doc)?;
         println!();
       } else {
-        let result = DocPrinter::new(&doc_nodes, true, false);
+        let result = DocPrinter::new(&merged_doc, true, false);
         println!("{result}");
       }
     }
@@ -379,7 +385,7 @@ fn generate_docs_directory(
   package_name: Option<String>,
   output_dir: PathBuf,
   main_entrypoint: Option<ModuleSpecifier>,
-  doc_nodes_by_url: IndexMap<ModuleSpecifier, Vec<deno_doc::Symbol>>,
+  doc_nodes_by_url: IndexMap<ModuleSpecifier, deno_doc::Document>,
 ) -> Result<(), anyhow::Error> {
   let cwd = current_dir().unwrap();
   let output_dir_resolved = cwd.join(output_dir);

js/mod.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { instantiate } from "./deno_doc_wasm.generated.js";
-import type { DocNode, Location } from "./types.d.ts";
+import type { Document, Location } from "./types.d.ts";
 import type { Page } from "./html_types.d.ts";
 import { createCache } from "@deno/cache-dir";
 import type { CacheSetting, LoadResponse } from "@deno/graph";
@@ -87,7 +87,7 @@ export interface DocOptions {
 export async function doc(
   specifiers: string[],
   options: DocOptions = {},
-): Promise<Record<string, Array<DocNode>>> {
+): Promise<Record<string, Document>> {
   const {
     load = createCache().load,
     includeAll = false,
@@ -303,12 +303,12 @@ const defaultUsageComposer: UsageComposer = {
 };
 
 /**
- * Generate HTML files for provided {@linkcode DocNode}s.
+ * Generate HTML files for provided {@linkcode Document}s.
  * @param docNodesByUrl DocNodes keyed by their absolute URL.
  * @param options Options for the generation.
  */
 export async function generateHtml(
-  docNodesByUrl: Record<string, Array<DocNode>>,
+  docNodesByUrl: Record<string, Document>,
   options: GenerateOptions,
 ): Promise<Record<string, string>> {
   const {
@@ -346,7 +346,7 @@ export async function generateHtml(
  * @param options Options for the generation.
  */
 export async function generateHtmlAsJSON(
-  docNodesByUrl: Record<string, Array<DocNode>>,
+  docNodesByUrl: Record<string, Document>,
   options: GenerateOptions,
 ): Promise<Record<string, Page>> {
   const {

js/test.ts

@@ -9,9 +9,9 @@ Deno.test({
     const records = await doc(
       ["https://deno.land/std@0.104.0/fmt/colors.ts"],
     );
-    const entries = records["https://deno.land/std@0.104.0/fmt/colors.ts"];
-    assertEquals(entries.length, 49);
-    const fnStripColor = entries.find((n) =>
+    const document = records["https://deno.land/std@0.104.0/fmt/colors.ts"];
+    assertEquals(document.symbols.length, 49);
+    const fnStripColor = document.symbols.find((n) =>
       n.declarations.some((d) => d.kind === "function") &&
       n.name === "stripColor"
     );
@@ -61,7 +61,7 @@ Deno.test({
 Deno.test({
   name: "doc() - with headers",
   async fn() {
-    const entries = await doc(["https://example.com/a"], {
+    const documents = await doc(["https://example.com/a"], {
       load(specifier) {
         return Promise.resolve({
           kind: "module",
@@ -75,7 +75,7 @@ Deno.test({
         });
       },
     });
-    assertEquals(Object.values(entries)[0].length, 1);
+    assertEquals(Object.values(documents)[0].symbols.length, 1);
   },
 });
 
@@ -121,10 +121,10 @@ Deno.test({
         });
       },
     });
-    const entries = Object.values(records)[0];
-    assertEquals(entries.length, 1);
-    assertEquals(entries[0].declarations[0].kind, "class");
-    assertEquals(entries[0].name, "B");
+    const document = Object.values(records)[0];
+    assertEquals(document.symbols.length, 1);
+    assertEquals(document.symbols[0].declarations[0].kind, "class");
+    assertEquals(document.symbols[0].name, "B");
   },
 });
 

js/types.d.ts

@@ -1,5 +1,10 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
+export interface Document {
+  moduleDoc?: JsDoc;
+  symbols: DocNode[];
+}
+
 export interface DocNode {
   name: string;
   isDefault?: true;

lib/lib.rs

@@ -5,7 +5,7 @@ use anyhow::Context;
 use deno_doc::html::UrlResolveKind;
 use deno_doc::html::UsageComposerEntry;
 use deno_doc::html::UsageToMd;
-use deno_doc::DocParser;
+use deno_doc::{DocParser, Document};
 use deno_graph::ast::CapturingModuleAnalyzer;
 use deno_graph::source::CacheSetting;
 use deno_graph::source::LoadError;
@@ -566,7 +566,7 @@ fn generate_html_inner(
   >(default_symbol_map)
   .map_err(|err| anyhow!("defaultSymbolMap: {}", err))?;
 
-  let doc_nodes_by_url: IndexMap<ModuleSpecifier, Vec<deno_doc::Symbol>> =
+  let doc_nodes_by_url: IndexMap<ModuleSpecifier, Document> =
     serde_wasm_bindgen::from_value(doc_nodes_by_url)
       .map_err(|err| anyhow!("docNodesByUrl: {}", err))?;
 

src/diagnostics.rs

@@ -402,9 +402,7 @@ impl DiagnosticDocNodeVisitor<'_, '_> {
         | DeclarationDef::Namespace(..)
         | DeclarationDef::TypeAlias(..)
         | DeclarationDef::Variable(..) => true,
-        DeclarationDef::Import(..)
-        | DeclarationDef::ModuleDoc
-        | DeclarationDef::Reference(..) => false,
+        DeclarationDef::Import(..) | DeclarationDef::Reference(..) => false,
       }
     }
 

src/diff/mod.rs

@@ -163,10 +163,10 @@ impl DocDiff {
     let mut modified_modules = IndexMap::new();
 
     for specifier in old_modules.intersection(&new_modules) {
-      let old_nodes = old.get(*specifier).unwrap();
-      let new_nodes = new.get(*specifier).unwrap();
+      let old_doc = old.get(*specifier).unwrap();
+      let new_doc = new.get(*specifier).unwrap();
 
-      let module_diff = ModuleDiff::diff(old_nodes, new_nodes);
+      let module_diff = ModuleDiff::diff(&old_doc.symbols, &new_doc.symbols);
 
       if module_diff.has_changes() {
         modified_modules.insert((*specifier).clone(), module_diff);
@@ -602,7 +602,6 @@ impl DeclarationDefDiff {
 
       (DeclarationDef::Import(..), DeclarationDef::Import(..)) => None,
       (DeclarationDef::Reference(..), DeclarationDef::Reference(..)) => None,
-      (DeclarationDef::ModuleDoc, DeclarationDef::ModuleDoc) => None,
 
       _ => unreachable!(),
     }

src/html/jsdoc.rs

@@ -1,6 +1,5 @@
 use super::render_context::RenderContext;
 use super::util::*;
-use crate::DeclarationDef;
 use crate::html::ShortPath;
 use crate::js_doc::JsDoc;
 use crate::js_doc::JsDocTag;
@@ -802,34 +801,30 @@ impl ModuleDocCtx {
 
     let mut sections = Vec::with_capacity(7);
 
-    let (deprecated, html) = if let Some(decl) =
-      module_doc_nodes.iter().find_map(|n| {
-        n.declarations
-          .iter()
-          .find(|decl| matches!(decl.def, DeclarationDef::ModuleDoc))
-      }) {
-      let deprecated = decl.js_doc.tags.iter().find_map(|tag| {
-        if let JsDocTag::Deprecated { doc } = tag {
-          Some(render_markdown(
-            render_ctx,
-            doc.as_deref().unwrap_or_default(),
-            false,
-          ))
-        } else {
-          None
-        }
-      });
+    let (deprecated, html) =
+      if let Some(js_doc) = render_ctx.ctx.module_docs.get(short_path) {
+        let deprecated = js_doc.tags.iter().find_map(|tag| {
+          if let JsDocTag::Deprecated { doc } = tag {
+            Some(render_markdown(
+              render_ctx,
+              doc.as_deref().unwrap_or_default(),
+              false,
+            ))
+          } else {
+            None
+          }
+        });
 
-      if let Some(examples) = jsdoc_examples(render_ctx, &decl.js_doc) {
-        sections.push(examples);
-      }
+        if let Some(examples) = jsdoc_examples(render_ctx, js_doc) {
+          sections.push(examples);
+        }
 
-      let html = jsdoc_body_to_html(render_ctx, &decl.js_doc, summary);
+        let html = jsdoc_body_to_html(render_ctx, js_doc, summary);
 
-      (deprecated, html)
-    } else {
-      (None, None)
-    };
+        (deprecated, html)
+      } else {
+        (None, None)
+      };
 
     if render_symbols {
       let partitions_by_kind = super::partition::partition_nodes_by_kind(
@@ -896,6 +891,7 @@ mod test {
   use crate::interface::InterfaceDef;
   use crate::js_doc::JsDoc;
   use crate::node::DeclarationKind;
+  use crate::node::Document;
 
   struct EmptyResolver;
 
@@ -984,26 +980,52 @@ mod test {
       IndexMap::from([
         (
           ModuleSpecifier::parse("file:///a.ts").unwrap(),
-          vec![
-            Symbol::interface(
-              "foo".into(),
-              false,
-              Location::default(),
-              DeclarationKind::Export,
-              JsDoc::default(),
-              InterfaceDef {
-                def_name: None,
-                extends: vec![],
-                constructors: vec![],
-                methods: vec![],
-                properties: vec![],
-                call_signatures: vec![],
-                index_signatures: vec![],
-                type_params: Box::new([]),
-              },
-            ),
-            Symbol::interface(
-              "bar".into(),
+          Document {
+            module_doc: Default::default(),
+            symbols: vec![
+              Symbol::interface(
+                "foo".into(),
+                false,
+                Location::default(),
+                DeclarationKind::Export,
+                JsDoc::default(),
+                InterfaceDef {
+                  def_name: None,
+                  extends: vec![],
+                  constructors: vec![],
+                  methods: vec![],
+                  properties: vec![],
+                  call_signatures: vec![],
+                  index_signatures: vec![],
+                  type_params: Box::new([]),
+                },
+              ),
+              Symbol::interface(
+                "bar".into(),
+                false,
+                Location::default(),
+                DeclarationKind::Export,
+                JsDoc::default(),
+                InterfaceDef {
+                  def_name: None,
+                  extends: vec![],
+                  constructors: vec![],
+                  methods: vec![],
+                  properties: vec![],
+                  call_signatures: vec![],
+                  index_signatures: vec![],
+                  type_params: Box::new([]),
+                },
+              ),
+            ],
+          },
+        ),
+        (
+          ModuleSpecifier::parse("file:///b.ts").unwrap(),
+          Document {
+            module_doc: Default::default(),
+            symbols: vec![Symbol::interface(
+              "baz".into(),
               false,
               Location::default(),
               DeclarationKind::Export,
@@ -1018,28 +1040,8 @@ mod test {
                 index_signatures: vec![],
                 type_params: Box::new([]),
               },
-            ),
-          ],
-        ),
-        (
-          ModuleSpecifier::parse("file:///b.ts").unwrap(),
-          vec![Symbol::interface(
-            "baz".into(),
-            false,
-            Location::default(),
-            DeclarationKind::Export,
-            JsDoc::default(),
-            InterfaceDef {
-              def_name: None,
-              extends: vec![],
-              constructors: vec![],
-              methods: vec![],
-              properties: vec![],
-              call_signatures: vec![],
-              index_signatures: vec![],
-              type_params: Box::new([]),
-            },
-          )],
+            )],
+          },
         ),
       ]),
       None,