feat: support leading @module JSDoc blocks (#167)

kitsonk · web-flow · commit ebcbcab03d0a · 2021-09-12T08:47:54.000+10:00
Closes: #42
diff --git a/lib/deno_doc.generated.js b/lib/deno_doc.generated.js
@@ -352,7 +352,7 @@ const imports = {
     __wbindgen_throw: function (arg0, arg1) {
       throw new Error(getStringFromWasm0(arg0, arg1));
     },
-    __wbindgen_closure_wrapper808: function (arg0, arg1, arg2) {
+    __wbindgen_closure_wrapper819: function (arg0, arg1, arg2) {
       var ret = makeMutClosure(arg0, arg1, 154, __wbg_adapter_16);
       return addHeapObject(ret);
     },
diff --git a/lib/deno_doc_bg.wasm b/lib/deno_doc_bg.wasm
diff --git a/lib/types.d.ts b/lib/types.d.ts
@@ -1,6 +1,7 @@
 // Copyright 2020-2021 the Deno authors. All rights reserved. MIT license.
 
 export type DocNode =
+  | DocNodeModuleDoc
   | DocNodeFunction
   | DocNodeVariable
   | DocNodeEnum
@@ -18,6 +19,7 @@ interface DocNodeBase {
 }
 
 export type DocNodeKind =
+  | "moduleDoc"
   | "function"
   | "variable"
   | "enum"
@@ -27,6 +29,11 @@ export type DocNodeKind =
   | "interface"
   | "import";
 
+export interface DocNodeModuleDoc extends DocNodeBase {
+  kind: "moduleDoc";
+  jsDoc: JsDoc;
+}
+
 export interface DocNodeFunction extends DocNodeBase {
   kind: "function";
   functionDef: FunctionDef;
@@ -206,6 +213,7 @@ export type JsDocTagKind =
   | "deprecated"
   | "enum"
   | "extends"
+  | "module"
   | "param"
   | "public"
   | "private"
@@ -234,7 +242,13 @@ export interface JsDocTagBase {
 }
 
 export interface JsDocTagOnly extends JsDocTagBase {
-  kind: "constructor" | "public" | "private" | "protected" | "readonly";
+  kind:
+    | "constructor"
+    | "module"
+    | "public"
+    | "private"
+    | "protected"
+    | "readonly";
 }
 
 export interface JsDocTagDoc extends JsDocTagBase {
diff --git a/src/js_doc.rs b/src/js_doc.rs
@@ -8,7 +8,7 @@ lazy_static! {
   static ref JS_DOC_TAG_MAYBE_DOC_RE: Regex = Regex::new(r#"^\s*@(deprecated)(?:\s+(.+))?"#).unwrap();
   static ref JS_DOC_TAG_NAMED_RE: Regex = Regex::new(r#"(?s)^\s*@(callback|template)\s+([a-zA-Z_$]\S*)(?:\s+(.+))?"#).unwrap();
   static ref JS_DOC_TAG_NAMED_TYPED_RE: Regex = Regex::new(r#"(?s)^\s*@(prop(?:erty)?|typedef)\s+\{([^}]+)\}\s+([a-zA-Z_$]\S*)(?:\s+(.+))?"#).unwrap();
-  static ref JS_DOC_TAG_ONLY_RE: Regex = Regex::new(r#"^\s*@(constructor|class|public|private|protected|readonly)"#).unwrap();
+  static ref JS_DOC_TAG_ONLY_RE: Regex = Regex::new(r#"^\s*@(constructor|class|module|public|private|protected|readonly)"#).unwrap();
   static ref JS_DOC_TAG_PARAM_RE: Regex = Regex::new(
     r#"(?s)^\s*@(?:param|arg(?:ument)?)(?:\s+\{([^}]+)\})?\s+([a-zA-Z_$]\S*)(?:\s+(.+))?"#
   )
@@ -66,7 +66,7 @@ impl From<String> for JsDoc {
   }
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, Eq, PartialEq)]
 #[serde(tag = "kind", rename_all = "lowercase")]
 pub enum JsDocTag {
   /// `@callback Predicate comment`
@@ -96,6 +96,8 @@ pub enum JsDocTag {
     #[serde(skip_serializing_if = "Option::is_none")]
     doc: Option<String>,
   },
+  /// `@module`
+  Module,
   /// `@param {type} name comment` or `@arg {type} name comment` or
   /// `@argument {type} name comment`
   Param {
@@ -168,6 +170,7 @@ impl From<String> for JsDocTag {
       let kind = caps.get(1).unwrap().as_str();
       match kind {
         "constructor" | "class" => Self::Constructor,
+        "module" => Self::Module,
         "public" => Self::Public,
         "private" => Self::Private,
         "protected" => Self::Protected,
diff --git a/src/node.rs b/src/node.rs
@@ -8,6 +8,7 @@ use crate::js_doc::JsDoc;
 #[derive(Debug, PartialEq, Serialize, Deserialize, Clone)]
 #[serde(rename_all = "camelCase")]
 pub enum DocNodeKind {
+  ModuleDoc,
   Function,
   Variable,
   Class,
@@ -93,7 +94,39 @@ pub struct DocNode {
   pub import_def: Option<ImportDef>,
 }
 
+impl Default for DocNode {
+  fn default() -> Self {
+    Self {
+      kind: DocNodeKind::ModuleDoc,
+      name: "".to_string(),
+      location: Location {
+        filename: "".to_string(),
+        line: 0,
+        col: 0,
+      },
+      js_doc: JsDoc::default(),
+      function_def: None,
+      variable_def: None,
+      enum_def: None,
+      class_def: None,
+      type_alias_def: None,
+      namespace_def: None,
+      interface_def: None,
+      import_def: None,
+    }
+  }
+}
+
 impl DocNode {
+  pub fn module_doc(location: Location, js_doc: JsDoc) -> Self {
+    Self {
+      kind: DocNodeKind::ModuleDoc,
+      name: "".to_string(),
+      location,
+      js_doc,
+      ..Default::default()
+    }
+  }
   pub fn function(
     name: String,
     location: Location,
@@ -106,13 +139,7 @@ impl DocNode {
       location,
       js_doc,
       function_def: Some(fn_def),
-      variable_def: None,
-      enum_def: None,
-      class_def: None,
-      type_alias_def: None,
-      namespace_def: None,
-      interface_def: None,
-      import_def: None,
+      ..Default::default()
     }
   }
 
@@ -127,14 +154,8 @@ impl DocNode {
       name,
       location,
       js_doc,
-      function_def: None,
       variable_def: Some(var_def),
-      enum_def: None,
-      class_def: None,
-      type_alias_def: None,
-      namespace_def: None,
-      interface_def: None,
-      import_def: None,
+      ..Default::default()
     }
   }
 
@@ -149,14 +170,8 @@ impl DocNode {
       name,
       location,
       js_doc,
-      function_def: None,
-      variable_def: None,
       enum_def: Some(enum_def),
-      class_def: None,
-      type_alias_def: None,
-      namespace_def: None,
-      interface_def: None,
-      import_def: None,
+      ..Default::default()
     }
   }
 
@@ -171,14 +186,8 @@ impl DocNode {
       name,
       location,
       js_doc,
-      function_def: None,
-      variable_def: None,
-      enum_def: None,
       class_def: Some(class_def),
-      type_alias_def: None,
-      namespace_def: None,
-      interface_def: None,
-      import_def: None,
+      ..Default::default()
     }
   }
 
@@ -193,14 +202,8 @@ impl DocNode {
       name,
       location,
       js_doc,
-      function_def: None,
-      variable_def: None,
-      enum_def: None,
-      class_def: None,
       type_alias_def: Some(type_alias_def),
-      namespace_def: None,
-      interface_def: None,
-      import_def: None,
+      ..Default::default()
     }
   }
 
@@ -215,14 +218,8 @@ impl DocNode {
       name,
       location,
       js_doc,
-      function_def: None,
-      variable_def: None,
-      enum_def: None,
-      class_def: None,
-      type_alias_def: None,
       namespace_def: Some(namespace_def),
-      interface_def: None,
-      import_def: None,
+      ..Default::default()
     }
   }
 
@@ -237,14 +234,8 @@ impl DocNode {
       name,
       location,
       js_doc,
-      function_def: None,
-      variable_def: None,
-      enum_def: None,
-      class_def: None,
-      type_alias_def: None,
-      namespace_def: None,
       interface_def: Some(interface_def),
-      import_def: None,
+      ..Default::default()
     }
   }
 
@@ -259,14 +250,8 @@ impl DocNode {
       name,
       location,
       js_doc,
-      function_def: None,
-      variable_def: None,
-      enum_def: None,
-      class_def: None,
-      type_alias_def: None,
-      namespace_def: None,
-      interface_def: None,
       import_def: Some(import_def),
+      ..Default::default()
     }
   }
 }
diff --git a/src/parser.rs b/src/parser.rs
@@ -7,6 +7,7 @@ use crate::node::DocNode;
 use crate::node::ModuleDoc;
 use crate::swc_util::get_location;
 use crate::swc_util::js_doc_for_span;
+use crate::swc_util::module_js_doc_for_source;
 use crate::ImportDef;
 use crate::Location;
 use crate::ReexportKind;
@@ -668,6 +669,13 @@ impl<'a> DocParser<'a> {
 
     let mut is_ambient = true;
 
+    // check to see if there is a module level JSDoc for the source file
+    if let Some((js_doc, span)) = module_js_doc_for_source(parsed_source) {
+      let doc_node =
+        DocNode::module_doc(get_location(parsed_source, span.lo), js_doc);
+      doc_entries.push(doc_node);
+    }
+
     for node in module_body.iter() {
       match node {
         ModuleItem::Stmt(stmt) => {
diff --git a/src/printer.rs b/src/printer.rs
@@ -96,14 +96,15 @@ impl<'a> DocPrinter<'a> {
 
   fn kind_order(&self, kind: &DocNodeKind) -> i64 {
     match kind {
-      DocNodeKind::Function => 0,
-      DocNodeKind::Variable => 1,
-      DocNodeKind::Class => 2,
-      DocNodeKind::Enum => 3,
-      DocNodeKind::Interface => 4,
-      DocNodeKind::TypeAlias => 5,
-      DocNodeKind::Namespace => 6,
-      DocNodeKind::Import => 7,
+      DocNodeKind::ModuleDoc => 0,
+      DocNodeKind::Function => 1,
+      DocNodeKind::Variable => 2,
+      DocNodeKind::Class => 3,
+      DocNodeKind::Enum => 4,
+      DocNodeKind::Interface => 5,
+      DocNodeKind::TypeAlias => 6,
+      DocNodeKind::Namespace => 7,
+      DocNodeKind::Import => 8,
     }
   }
 
@@ -114,6 +115,7 @@ impl<'a> DocPrinter<'a> {
     indent: i64,
   ) -> FmtResult {
     match node.kind {
+      DocNodeKind::ModuleDoc => self.format_module_doc(w, node, indent),
       DocNodeKind::Function => self.format_function_signature(w, node, indent),
       DocNodeKind::Variable => self.format_variable_signature(w, node, indent),
       DocNodeKind::Class => self.format_class_signature(w, node, indent),
@@ -360,6 +362,17 @@ impl<'a> DocPrinter<'a> {
     writeln!(w)
   }
 
+  fn format_module_doc(
+    &self,
+    _w: &mut Formatter<'_>,
+    _node: &DocNode,
+    _indent: i64,
+  ) -> FmtResult {
+    // currently we do not print out JSDoc in the printer, so there is nothing
+    // to print.
+    Ok(())
+  }
+
   fn format_type_alias_signature(
     &self,
     w: &mut Formatter<'_>,
diff --git a/src/swc_util.rs b/src/swc_util.rs
diff --git a/src/tests.rs b/src/tests.rs
