doc: Remove detailed / summary distinction (#6818)

3 files changed, 58 insertions, 195 deletions

diff --git a/cli/doc/printer.rs b/cli/doc/printer.rs
index 5ba5154c5..01609d0e2 100644
--- a/cli/doc/printer.rs
+++ b/cli/doc/printer.rs
@@ -20,32 +20,19 @@ use std::fmt::{Display, Formatter, Result as FmtResult};
 
 pub struct DocPrinter<'a> {
   doc_nodes: &'a [doc::DocNode],
-  details: bool,
   private: bool,
 }
 
 impl<'a> DocPrinter<'a> {
-  pub fn new(
-    doc_nodes: &[doc::DocNode],
-    details: bool,
-    private: bool,
-  ) -> DocPrinter {
-    DocPrinter {
-      doc_nodes,
-      details,
-      private,
-    }
+  pub fn new(doc_nodes: &[doc::DocNode], private: bool) -> DocPrinter {
+    DocPrinter { doc_nodes, private }
   }
 
   pub fn format(&self, w: &mut Formatter<'_>) -> FmtResult {
-    if self.details {
-      self.format_details(w, self.doc_nodes, 0)
-    } else {
-      self.format_summary(w, self.doc_nodes, 0)
-    }
+    self.format_(w, self.doc_nodes, 0)
   }
 
-  fn format_summary(
+  fn format_(
     &self,
     w: &mut Formatter<'_>,
     doc_nodes: &[doc::DocNode],
@@ -61,36 +48,7 @@ impl<'a> DocPrinter<'a> {
       }
     });
 
-    for node in sorted {
-      self.format_signature(w, &node, indent)?;
-
-      if let Some(js_doc) = &node.js_doc {
-        self.format_jsdoc(w, js_doc, indent + 1, self.details)?;
-      }
-
-      writeln!(w)?;
-
-      if DocNodeKind::Namespace == node.kind {
-        self.format_summary(
-          w,
-          &node.namespace_def.as_ref().unwrap().elements,
-          indent + 1,
-        )?;
-
-        writeln!(w)?;
-      };
-    }
-
-    Ok(())
-  }
-
-  fn format_details(
-    &self,
-    w: &mut Formatter<'_>,
-    doc_nodes: &[doc::DocNode],
-    indent: i64,
-  ) -> FmtResult {
-    for node in doc_nodes {
+    for node in &sorted {
       write!(
         w,
         "{}",
@@ -104,15 +62,15 @@ impl<'a> DocPrinter<'a> {
 
       let js_doc = &node.js_doc;
       if let Some(js_doc) = js_doc {
-        self.format_jsdoc(w, js_doc, indent + 1, self.details)?;
+        self.format_jsdoc(w, js_doc, indent + 1)?;
       }
       writeln!(w)?;
 
       match node.kind {
-        DocNodeKind::Class => self.format_class_details(w, node)?,
-        DocNodeKind::Enum => self.format_enum_details(w, node)?,
-        DocNodeKind::Interface => self.format_interface_details(w, node)?,
-        DocNodeKind::Namespace => self.format_namespace_details(w, node)?,
+        DocNodeKind::Class => self.format_class(w, node)?,
+        DocNodeKind::Enum => self.format_enum(w, node)?,
+        DocNodeKind::Interface => self.format_interface(w, node)?,
+        DocNodeKind::Namespace => self.format_namespace(w, node)?,
         _ => {}
       }
     }
@@ -163,22 +121,15 @@ impl<'a> DocPrinter<'a> {
     w: &mut Formatter<'_>,
     jsdoc: &str,
     indent: i64,
-    details: bool,
   ) -> FmtResult {
     for line in jsdoc.lines() {
-      // Only show the first paragraph when summarising
-      // This should use the @summary JSDoc tag instead
-      if !details && line.is_empty() {
-        break;
-      }
-
       writeln!(w, "{}{}", Indent(indent), colors::gray(&line))?;
     }
 
     Ok(())
   }
 
-  fn format_class_details(
+  fn format_class(
     &self,
     w: &mut Formatter<'_>,
     node: &doc::DocNode,
@@ -187,7 +138,7 @@ impl<'a> DocPrinter<'a> {
     for node in &class_def.constructors {
       writeln!(w, "{}{}", Indent(1), node,)?;
       if let Some(js_doc) = &node.js_doc {
-        self.format_jsdoc(w, &js_doc, 2, self.details)?;
+        self.format_jsdoc(w, &js_doc, 2)?;
       }
     }
     for node in class_def.properties.iter().filter(|node| {
@@ -199,7 +150,7 @@ impl<'a> DocPrinter<'a> {
     }) {
       writeln!(w, "{}{}", Indent(1), node,)?;
       if let Some(js_doc) = &node.js_doc {
-        self.format_jsdoc(w, &js_doc, 2, self.details)?;
+        self.format_jsdoc(w, &js_doc, 2)?;
       }
     }
     for index_sign_def in &class_def.index_signatures {
@@ -214,13 +165,13 @@ impl<'a> DocPrinter<'a> {
     }) {
       writeln!(w, "{}{}", Indent(1), node,)?;
       if let Some(js_doc) = &node.js_doc {
-        self.format_jsdoc(w, js_doc, 2, self.details)?;
+        self.format_jsdoc(w, js_doc, 2)?;
       }
     }
     writeln!(w)
   }
 
-  fn format_enum_details(
+  fn format_enum(
     &self,
     w: &mut Formatter<'_>,
     node: &doc::DocNode,
@@ -232,7 +183,7 @@ impl<'a> DocPrinter<'a> {
     writeln!(w)
   }
 
-  fn format_interface_details(
+  fn format_interface(
     &self,
     w: &mut Formatter<'_>,
     node: &doc::DocNode,
@@ -242,13 +193,13 @@ impl<'a> DocPrinter<'a> {
     for property_def in &interface_def.properties {
       writeln!(w, "{}{}", Indent(1), property_def)?;
       if let Some(js_doc) = &property_def.js_doc {
-        self.format_jsdoc(w, js_doc, 2, self.details)?;
+        self.format_jsdoc(w, js_doc, 2)?;
       }
     }
     for method_def in &interface_def.methods {
       writeln!(w, "{}{}", Indent(1), method_def)?;
       if let Some(js_doc) = &method_def.js_doc {
-        self.format_jsdoc(w, js_doc, 2, self.details)?;
+        self.format_jsdoc(w, js_doc, 2)?;
       }
     }
     for index_sign_def in &interface_def.index_signatures {
@@ -257,7 +208,7 @@ impl<'a> DocPrinter<'a> {
     writeln!(w)
   }
 
-  fn format_namespace_details(
+  fn format_namespace(
     &self,
     w: &mut Formatter<'_>,
     node: &doc::DocNode,
@@ -266,7 +217,7 @@ impl<'a> DocPrinter<'a> {
     for node in elements {
       self.format_signature(w, &node, 1)?;
       if let Some(js_doc) = &node.js_doc {
-        self.format_jsdoc(w, js_doc, 2, false)?;
+        self.format_jsdoc(w, js_doc, 2)?;
       }
     }
     writeln!(w)
diff --git a/cli/doc/tests.rs b/cli/doc/tests.rs
index 94d087ea3..2faf617cc 100644
--- a/cli/doc/tests.rs
+++ b/cli/doc/tests.rs
@@ -44,26 +44,17 @@ impl DocFileLoader for TestLoader {
 
 macro_rules! doc_test {
   ( $name:ident, $source:expr; $block:block ) => {
-    doc_test!($name, $source, false, false; $block);
-  };
-
-  ( $name:ident, $source:expr, details; $block:block ) => {
-    doc_test!($name, $source, true, false; $block);
+    doc_test!($name, $source, false; $block);
   };
 
   ( $name:ident, $source:expr, private; $block:block ) => {
-    doc_test!($name, $source, false, true; $block);
-  };
-
-  ( $name:ident, $source:expr, details, private; $block:block ) => {
-    doc_test!($name, $source, true, true; $block);
+    doc_test!($name, $source, true; $block);
   };
 
-  ( $name:ident, $source:expr, $details:expr, $private:expr; $block:block ) => {
+  ( $name:ident, $source:expr, $private:expr; $block:block ) => {
     #[tokio::test]
     async fn $name() {
       let source_code = $source;
-      let details = $details;
       let private = $private;
 
       let loader =
@@ -73,7 +64,7 @@ macro_rules! doc_test {
         .await
         .unwrap();
 
-      let doc = DocPrinter::new(&entries, details, private).to_string();
+      let doc = DocPrinter::new(&entries, private).to_string();
       #[allow(unused_variables)]
       let doc = colors::strip_ansi_codes(&doc);
 
@@ -85,27 +76,17 @@ macro_rules! doc_test {
 macro_rules! contains_test {
   ( $name:ident, $source:expr;
     $( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
-    contains_test!($name, $source, false, false; $($contains),* $(;$($notcontains),*)?);
-  };
-
-  ( $name:ident, $source:expr, details;
-    $( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
-    contains_test!($name, $source, true, false; $($contains),* $(;$($notcontains),*)?);
+    contains_test!($name, $source, false; $($contains),* $(;$($notcontains),*)?);
   };
 
   ( $name:ident, $source:expr, private;
     $( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
-    contains_test!($name, $source, false, true; $($contains),* $(;$($notcontains),*)?);
+    contains_test!($name, $source, true; $($contains),* $(;$($notcontains),*)?);
   };
 
-  ( $name:ident, $source:expr, details, private;
+  ( $name:ident, $source:expr, $private:expr;
     $( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
-    contains_test!($name, $source, true, true; $($contains),* $(;$($notcontains),*)?);
-  };
-
-  ( $name:ident, $source:expr, $details:expr, $private:expr;
-    $( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
-    doc_test!($name, $source, $details, $private; {
+    doc_test!($name, $source, $private; {
       $(
         assert!(doc.contains($contains));
       )*
@@ -128,7 +109,7 @@ macro_rules! json_test {
   };
 
   ( $name:ident, $source:expr, $private:expr; $json:tt ) => {
-    doc_test!($name, $source, false, $private; {
+    doc_test!($name, $source, $private; {
       let actual = serde_json::to_value(&entries).unwrap();
       let expected_json = json!($json);
       assert_eq!(actual, expected_json);
@@ -244,7 +225,7 @@ export function fooFn(a: number) {
   assert_eq!(actual, expected_json);
 
   assert!(colors::strip_ansi_codes(
-    DocPrinter::new(&entries, false, false).to_string().as_str()
+    DocPrinter::new(&entries, false).to_string().as_str()
   )
   .contains("function fooFn(a: number)"));
 }
@@ -1606,8 +1587,7 @@ mod printer {
   use super::*;
 
   contains_test!(abstract_class,
-    "export abstract class Class {}",
-    details;
+    "export abstract class Class {}";
     "abstract class Class"
   );
 
@@ -1616,8 +1596,7 @@ mod printer {
 export abstract class Class {
   abstract method() {}
 }
-    "#,
-    details;
+    "#;
     "abstract method()"
   );
 
@@ -1626,8 +1605,7 @@ export abstract class Class {
 export class Class {
   async amethod(v) {}
 }
-    "#,
-    details;
+    "#;
     "async amethod(v)"
   );
 
@@ -1636,22 +1614,18 @@ export class Class {
 export class Class {
   constructor(a, b) {}
 }
-    "#,
-    details;
+    "#;
     "constructor(a, b)"
   );
 
-  const CLASS_SOURCE: &str = r#"
+  contains_test!(class_details,
+    r#"
 export class C {
   /** a doc */
   a() {}
   f: number;
 }
     "#;
-
-  contains_test!(class_details,
-    CLASS_SOURCE,
-    details;
     "class C",
     "a()",
     "f: number"
@@ -1665,7 +1639,6 @@ export class Class {
   public pub() {}
 }
     "#,
-    details,
     private;
     "private pri()",
     "protected pro()",
@@ -1679,8 +1652,7 @@ export class Class {
   protected pro() {}
   public pub() {}
 }
-    "#,
-    details;
+    "#;
     "protected pro()",
     "pub()"
   );
@@ -1711,8 +1683,7 @@ export class Class {
   get a(): void {}
   set b(_v: void) {}
 }
-    "#,
-    details;
+    "#;
     "get a(): void",
     "set b(_v: void)"
   );
@@ -1722,8 +1693,7 @@ export class Class {
 export class C {
   [key: string]: number;
 }
-    "#,
-    details;
+    "#;
     "[key: string]: number"
   );
 
@@ -1742,8 +1712,7 @@ export class C {
 export class Class {
   method(v) {}
 }
-    "#,
-    details;
+    "#;
     "method(v)"
   );
 
@@ -1753,8 +1722,7 @@ export class Class {
   someproperty: bool;
   optproperty: bigint;
 }
-    "#,
-    details;
+    "#;
     "someproperty: bool",
     "optproperty: bigint"
   );
@@ -1764,8 +1732,7 @@ export class Class {
 export class C {
   readonly [key: string]: number;
 }
-    "#,
-    details;
+    "#;
     "readonly [key: string]: number"
   );
 
@@ -1774,25 +1741,16 @@ export class C {
 export class Class {
   static property = "";
 }
-    "#,
-    details;
+    "#;
     "static property"
   );
 
-  contains_test!(class_summary,
-    CLASS_SOURCE;
-    "class C";
-    "a()",
-    "f: number"
-  );
-
   contains_test!(class_readonly_property,
     r#"
 export class Class {
   readonly property = "";
 }
-    "#,
-    details;
+    "#;
     "readonly property"
   );
 
@@ -1802,7 +1760,6 @@ export class Class {
   private property = "";
 }
     "#,
-    details,
     private;
     "private property"
   );
@@ -1817,7 +1774,8 @@ export class Class {
     "enum Enum"
   );
 
-  const EXPORT_SOURCE: &str = r#"
+  contains_test!(exports_all_with_private,
+    r#"
 export function a() {}
 function b() {}
 export class C {}
@@ -1826,10 +1784,7 @@ export interface E {}
 interface F {}
 export namespace G {}
 namespace H {}
-    "#;
-
-  contains_test!(exports_all_with_private,
-    EXPORT_SOURCE,
+    "#,
     private;
     "function a()",
     "class C",
@@ -1841,18 +1796,6 @@ namespace H {}
     "namespace H"
   );
 
-  contains_test!(exports_only_exports_without_private,
-    EXPORT_SOURCE;
-    "function a()",
-    "class C",
-    "interface E",
-    "namespace G";
-    "function b()",
-    "class D",
-    "interface F",
-    "namespace H"
-  );
-
   contains_test!(function_async,
     "export async function a() {}";
     "async function a()"
@@ -1952,8 +1895,7 @@ export function f(): Generic<[string, number]> { return {}; }
 export interface Interface {
   [index: number]: Interface;
 }
-    "#,
-    details;
+    "#;
     "[index: number]: Interface"
   );
 
@@ -1963,8 +1905,7 @@ export interface I {
   m(a, b);
   mo?(c);
 }
-    "#,
-    details;
+    "#;
     "m(a, b)",
     "mo?(c)"
   );
@@ -1975,8 +1916,7 @@ export interface I {
   p: string;
   po?: number;
 }
-    "#,
-    details;
+    "#;
     "p: string",
     "po?: number"
   );
@@ -1986,12 +1926,12 @@ export interface I {
 export interface Interface {
   readonly [index: number]: Interface;
 }
-    "#,
-    details;
+    "#;
     "readonly [index: number]: Interface"
   );
 
-  const JSDOC_SOURCE: &str = r#"
+  contains_test!(jsdoc,
+    r#"
 /**
  * A is a class
  *
@@ -2011,10 +1951,6 @@ export interface B {}
  */
 export function C() {}
     "#;
-
-  contains_test!(jsdoc_details,
-    JSDOC_SOURCE,
-    details;
     "A is a class",
     "B is an interface",
     "C is a function",
@@ -2023,22 +1959,13 @@ export function C() {}
     "Summarised"
   );
 
-  contains_test!(jsdoc_summary,
-    JSDOC_SOURCE;
-    "A is a class",
-    "B is an interface",
-    "C is a function";
-    "Nothing more",
-    "Should be",
-    "Summarised"
-  );
-
   contains_test!(namespace_declaration,
   "export namespace Namespace {}";
     "namespace Namespace"
   );
 
-  const NAMESPACE_SOURCE: &str = r#"
+  contains_test!(namespace_details,
+    r#"
 export namespace Namespace {
   /**
    * Doc comment 1
@@ -2054,26 +1981,11 @@ export namespace Namespace {
   export class B {}
 }
     "#;
-
-  contains_test!(namespace_details,
-    NAMESPACE_SOURCE,
-    details;
-    "namespace Namespace",
-    "function a()",
-    "class B",
-    "Doc comment 1",
-    "Doc comment 2";
-    "Details 1",
-    "Details 2"
-  );
-
-  contains_test!(namespace_summary,
-    NAMESPACE_SOURCE;
     "namespace Namespace",
     "function a()",
     "class B",
     "Doc comment 1",
-    "Doc comment 2";
+    "Doc comment 2",
     "Details 1",
     "Details 2"
   );
diff --git a/cli/main.rs b/cli/main.rs
index 799d47e32..5400d3f65 100644
--- a/cli/main.rs
+++ b/cli/main.rs
@@ -551,9 +551,9 @@ async fn doc_command(
         eprintln!("Node {} was not found!", filter);
         std::process::exit(1);
       }
-      format!("{}", doc::DocPrinter::new(&nodes, true, private))
+      format!("{}", doc::DocPrinter::new(&nodes, private))
     } else {
-      format!("{}", doc::DocPrinter::new(&doc_nodes, false, private))
+      format!("{}", doc::DocPrinter::new(&doc_nodes, private))
     };
 
     write_to_stdout_ignore_sigpipe(details.as_bytes()).map_err(ErrBox::from)