mirror of
https://github.com/denoland/deno.git
synced 2024-12-22 23:34:47 -05:00
doc: Remove detailed / summary distinction (#6818)
This commit is contained in:
Valentin Anger
GitHub
parent
f32d28019d
commit
d7077b9073
3 changed files with 58 additions and 195 deletions
|
|
@ -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)
|
||||
|
|
|
|||
160
cli/doc/tests.rs
160
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);
|
||||
doc_test!($name, $source, true; $block);
|
||||
};
|
||||
|
||||
( $name:ident, $source:expr, details, private; $block:block ) => {
|
||||
doc_test!($name, $source, true, 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"
|
||||
);
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue