feat: symbol restructure (#774)

Author: crowlKats

examples/ddoc/main.rs

@@ -13,7 +13,7 @@ use deno_doc::html::HrefResolver;
 use deno_doc::html::UrlResolveKind;
 use deno_doc::html::UsageComposer;
 use deno_doc::html::UsageComposerEntry;
-use deno_doc::node::DocNodeDef;
+use deno_doc::node::DeclarationDef;
 use deno_graph::BuildOptions;
 use deno_graph::GraphKind;
 use deno_graph::ModuleGraph;
@@ -213,8 +213,9 @@ async fn run() -> anyhow::Result<()> {
       let mut doc_nodes =
         doc_nodes_by_url.into_values().flatten().collect::<Vec<_>>();
 
-      doc_nodes
-        .retain(|doc_node| !matches!(doc_node.def, DocNodeDef::Import { .. }));
+      doc_nodes.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);
@@ -378,7 +379,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::DocNode>>,
+  doc_nodes_by_url: IndexMap<ModuleSpecifier, Vec<deno_doc::Symbol>>,
 ) -> Result<(), anyhow::Error> {
   let cwd = current_dir().unwrap();
   let output_dir_resolved = cwd.join(output_dir);

js/test.ts

@@ -12,12 +12,14 @@ Deno.test({
     const entries = records["https://deno.land/std@0.104.0/fmt/colors.ts"];
     assertEquals(entries.length, 49);
     const fnStripColor = entries.find((n) =>
-      n.kind === "function" && n.name === "stripColor"
+      n.declarations.some((d) => d.kind === "function") &&
+      n.name === "stripColor"
     );
     assert(fnStripColor, "unable to locate specific node");
-    assert(fnStripColor.kind === "function");
-    assert(fnStripColor.functionDef);
-    assertEquals(fnStripColor.functionDef.params, [{
+    const decl = fnStripColor.declarations[0];
+    assert(decl.kind === "function");
+    assert(decl.functionDef);
+    assertEquals(decl.functionDef.params, [{
       kind: "identifier",
       name: "string",
       optional: false,
@@ -121,7 +123,7 @@ Deno.test({
     });
     const entries = Object.values(records)[0];
     assertEquals(entries.length, 1);
-    assertEquals(entries[0].kind, "class");
+    assertEquals(entries[0].declarations[0].kind, "class");
     assertEquals(entries[0].name, "B");
   },
 });

js/types.d.ts

@@ -1,29 +1,33 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
-export type DocNode =
-  | DocNodeModuleDoc
-  | DocNodeFunction
-  | DocNodeVariable
-  | DocNodeEnum
-  | DocNodeClass
-  | DocNodeTypeAlias
-  | DocNodeNamespace
-  | DocNodeInterface
-  | DocNodeImport
-  | DocNodeReference;
+export interface DocNode {
+  name: string;
+  isDefault?: true;
+  declarations: Declaration[];
+}
 
 /** Indicates how the documentation node was declared. `"private"` indicates
  * the node is un-exported. `"export"` indicates it is exported from the current
  * module. `"declare"` indicates that it is a type only declaration. */
 export type DeclarationKind = "private" | "export" | "declare";
 
-interface DocNodeBase {
+export type Declaration =
+  | DeclarationModuleDoc
+  | DeclarationFunction
+  | DeclarationVariable
+  | DeclarationEnum
+  | DeclarationClass
+  | DeclarationTypeAlias
+  | DeclarationNamespace
+  | DeclarationInterface
+  | DeclarationImport
+  | DeclarationReference;
+
+interface DeclarationBase {
   kind: DocNodeKind;
-  name: string;
   location: Location;
   declarationKind: DeclarationKind;
   jsDoc?: JsDoc;
-  isDefault?: true;
 }
 
 export type DocNodeKind =
@@ -38,52 +42,52 @@ export type DocNodeKind =
   | "import"
   | "reference";
 
-export interface DocNodeModuleDoc extends DocNodeBase {
+export interface DeclarationModuleDoc extends DeclarationBase {
   kind: "moduleDoc";
   jsDoc: JsDoc;
 }
 
-export interface DocNodeFunction extends DocNodeBase {
+export interface DeclarationFunction extends DeclarationBase {
   kind: "function";
   functionDef: FunctionDef;
 }
 
-export interface DocNodeVariable extends DocNodeBase {
+export interface DeclarationVariable extends DeclarationBase {
   kind: "variable";
   variableDef: VariableDef;
 }
 
-export interface DocNodeEnum extends DocNodeBase {
+export interface DeclarationEnum extends DeclarationBase {
   kind: "enum";
   enumDef: EnumDef;
 }
 
-export interface DocNodeClass extends DocNodeBase {
+export interface DeclarationClass extends DeclarationBase {
   kind: "class";
   classDef: ClassDef;
 }
 
-export interface DocNodeTypeAlias extends DocNodeBase {
+export interface DeclarationTypeAlias extends DeclarationBase {
   kind: "typeAlias";
   typeAliasDef: TypeAliasDef;
 }
 
-export interface DocNodeNamespace extends DocNodeBase {
+export interface DeclarationNamespace extends DeclarationBase {
   kind: "namespace";
   namespaceDef: NamespaceDef;
 }
 
-export interface DocNodeInterface extends DocNodeBase {
+export interface DeclarationInterface extends DeclarationBase {
   kind: "interface";
   interfaceDef: InterfaceDef;
 }
 
-export interface DocNodeImport extends DocNodeBase {
+export interface DeclarationImport extends DeclarationBase {
   kind: "import";
   importDef: ImportDef;
 }
 
-export interface DocNodeReference extends DocNodeBase {
+export interface DeclarationReference extends DeclarationBase {
   kind: "reference";
   reference_def: ReferenceDef;
 }

lib/lib.rs

@@ -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::DocNode>> =
+  let doc_nodes_by_url: IndexMap<ModuleSpecifier, Vec<deno_doc::Symbol>> =
     serde_wasm_bindgen::from_value(doc_nodes_by_url)
       .map_err(|err| anyhow!("docNodesByUrl: {}", err))?;
 

src/class.rs

@@ -5,7 +5,6 @@ use deno_graph::symbols::EsModuleInfo;
 use serde::Deserialize;
 use serde::Serialize;
 
-use crate::DocNode;
 use crate::Location;
 use crate::ParamDef;
 use crate::decorators::DecoratorDef;
@@ -14,6 +13,7 @@ use crate::function::FunctionDef;
 use crate::function::function_to_function_def;
 use crate::js_doc::JsDoc;
 use crate::node::DeclarationKind;
+use crate::node::Symbol;
 use crate::params::assign_pat_to_param_def;
 use crate::params::ident_to_param_def;
 use crate::params::param_to_param_def;
@@ -124,9 +124,9 @@ pub struct ClassPropertyDef {
   pub location: Location,
 }
 
-impl From<ClassPropertyDef> for DocNode {
-  fn from(def: ClassPropertyDef) -> DocNode {
-    DocNode::variable(
+impl From<ClassPropertyDef> for Symbol {
+  fn from(def: ClassPropertyDef) -> Symbol {
+    Symbol::variable(
       def.name,
       false,
       def.location,
@@ -178,9 +178,9 @@ pub struct ClassMethodDef {
   pub location: Location,
 }
 
-impl From<ClassMethodDef> for DocNode {
-  fn from(def: ClassMethodDef) -> DocNode {
-    DocNode::function(
+impl From<ClassMethodDef> for Symbol {
+  fn from(def: ClassMethodDef) -> Symbol {
+    Symbol::function(
       def.name,
       false,
       def.location,
@@ -463,10 +463,6 @@ pub fn class_to_class_def(
 pub fn get_doc_for_class_decl(
   module_info: &EsModuleInfo,
   class_decl: &deno_ast::swc::ast::ClassDecl,
-) -> (String, ClassDef, JsDoc) {
-  let class_name = class_decl.ident.sym.to_string();
-  let (class_def, js_doc) =
-    class_to_class_def(module_info, &class_decl.class, None);
-
-  (class_name, class_def, js_doc)
+) -> (ClassDef, JsDoc) {
+  class_to_class_def(module_info, &class_decl.class, None)
 }