refactor: separate module doc from docnodes

Author: crowlKats

examples/ddoc/main.rs

@@ -210,22 +210,27 @@ 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 +384,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 { DocNode, 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

@@ -403,7 +403,6 @@ impl DiagnosticDocNodeVisitor<'_, '_> {
         | DeclarationDef::TypeAlias(..)
         | DeclarationDef::Variable(..) => true,
         DeclarationDef::Import(..)
-        | DeclarationDef::ModuleDoc
         | 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,13 +801,10 @@ 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| {
+    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,
@@ -820,11 +816,11 @@ impl ModuleDocCtx {
         }
       });
 
-      if let Some(examples) = jsdoc_examples(render_ctx, &decl.js_doc) {
+      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 {
@@ -896,6 +892,7 @@ mod test {
   use crate::interface::InterfaceDef;
   use crate::js_doc::JsDoc;
   use crate::node::DeclarationKind;
+  use crate::node::Document;
 
   struct EmptyResolver;
 
@@ -984,46 +981,51 @@ 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(),
-              false,
-              Location::default(),
-              DeclarationKind::Export,
-              JsDoc::default(),
-              InterfaceDef {
-                def_name: None,
-                extends: vec![],
-                constructors: vec![],
+          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(),
-          vec![Symbol::interface(
+          Document {
+            module_doc: Default::default(),
+            symbols: vec![Symbol::interface(
             "baz".into(),
             false,
             Location::default(),
@@ -1040,6 +1042,7 @@ mod test {
               type_params: Box::new([]),
             },
           )],
+          },
         ),
       ]),
       None,

src/html/mod.rs

@@ -286,6 +286,7 @@ pub struct GenerateOptions {
 pub struct GenerateCtx {
   pub package_name: Option<String>,
   pub common_ancestor: Option<PathBuf>,
+  pub module_docs: IndexMap<Rc<ShortPath>, crate::js_doc::JsDoc>,
   pub doc_nodes: IndexMap<Rc<ShortPath>, Vec<DocNodeWithContext>>,
   pub href_resolver: Rc<dyn HrefResolver>,
   pub usage_composer: Option<Rc<dyn UsageComposer>>,
@@ -321,10 +322,11 @@ impl GenerateCtx {
     let diff = diff.map(DiffIndex::new);
 
     let mut main_entrypoint = None;
+    let mut module_docs = IndexMap::new();
 
     let mut doc_nodes = doc_nodes_by_url
       .into_iter()
-      .map(|(specifier, nodes)| {
+      .map(|(specifier, document)| {
         let short_path = Rc::new(ShortPath::new(
           specifier,
           options.main_entrypoint.as_ref(),
@@ -336,7 +338,10 @@ impl GenerateCtx {
           main_entrypoint = Some(short_path.clone());
         }
 
-        let nodes = nodes
+        module_docs.insert(short_path.clone(), document.module_doc);
+
+        let nodes = document
+          .symbols
           .into_iter()
           .map(|mut symbol| {
             if &*symbol.name == "default"
@@ -523,6 +528,7 @@ impl GenerateCtx {
     Ok(Self {
       package_name: options.package_name,
       common_ancestor,
+      module_docs,
       doc_nodes,
       href_resolver: options.href_resolver,
       usage_composer: options.usage_composer,

src/html/pages.rs

@@ -253,19 +253,14 @@ impl IndexCtx {
         let sections = ctx
           .doc_nodes
           .iter()
-          .map(|(short_path, nodes)| {
-            let doc = nodes
-              .iter()
-              .find_map(|node| {
-                node
-                  .declarations
-                  .iter()
-                  .find(|decl| matches!(decl.def, DeclarationDef::ModuleDoc))
-              })
-              .and_then(|node| {
+          .map(|(short_path, _nodes)| {
+            let doc = ctx
+              .module_docs
+              .get(short_path)
+              .and_then(|js_doc| {
                 crate::html::jsdoc::jsdoc_body_to_html(
                   &render_ctx,
-                  &node.js_doc,
+                  js_doc,
                   true,
                 )
               });