foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-22 23:34:47 -05:00
Code Issues Packages 1 Wiki Activity

doc: Remove detailed / summary distinction (#6818)

Browse source
This commit is contained in:
Valentin Anger 2020-08-11 11:06:55 +02:00 committed by GitHub
parent f32d28019d
commit d7077b9073
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 58 additions and 195 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
cli/doc/printer.rs
View file

@ -20,32 +20,19 @@ use std::fmt::{Display, Formatter, Result as FmtResult};
pub struct DocPrinter<'a> { pub struct DocPrinter<'a> {
doc_nodes: &'a [doc::DocNode], doc_nodes: &'a [doc::DocNode],
details: bool,
private: bool, private: bool,
} }
impl<'a> DocPrinter<'a> { impl<'a> DocPrinter<'a> {
pub fn new( pub fn new(doc_nodes: &[doc::DocNode], private: bool) -> DocPrinter {
doc_nodes: &[doc::DocNode], DocPrinter { doc_nodes, private }
details: bool,
private: bool,
) -> DocPrinter {
DocPrinter {
doc_nodes,
details,
private,
}
} }
pub fn format(&self, w: &mut Formatter<'_>) -> FmtResult { pub fn format(&self, w: &mut Formatter<'_>) -> FmtResult {
if self.details { self.format_(w, self.doc_nodes, 0)
self.format_details(w, self.doc_nodes, 0)
} else {
self.format_summary(w, self.doc_nodes, 0)
}
} }
fn format_summary( fn format_(
&self, &self,
w: &mut Formatter<'_>, w: &mut Formatter<'_>,
doc_nodes: &[doc::DocNode], doc_nodes: &[doc::DocNode],
@ -61,36 +48,7 @@ impl<'a> DocPrinter<'a> {
} }
}); });
for node in sorted { 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 {
write!( write!(
w, w,
"{}", "{}",
@ -104,15 +62,15 @@ impl<'a> DocPrinter<'a> {
let js_doc = &node.js_doc; let js_doc = &node.js_doc;
if let Some(js_doc) = 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)?; writeln!(w)?;
match node.kind { match node.kind {
DocNodeKind::Class => self.format_class_details(w, node)?, DocNodeKind::Class => self.format_class(w, node)?,
DocNodeKind::Enum => self.format_enum_details(w, node)?, DocNodeKind::Enum => self.format_enum(w, node)?,
DocNodeKind::Interface => self.format_interface_details(w, node)?, DocNodeKind::Interface => self.format_interface(w, node)?,
DocNodeKind::Namespace => self.format_namespace_details(w, node)?, DocNodeKind::Namespace => self.format_namespace(w, node)?,
_ => {} _ => {}
} }
} }
@ -163,22 +121,15 @@ impl<'a> DocPrinter<'a> {
w: &mut Formatter<'_>, w: &mut Formatter<'_>,
jsdoc: &str, jsdoc: &str,
indent: i64, indent: i64,
details: bool,
) -> FmtResult { ) -> FmtResult {
for line in jsdoc.lines() { 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))?; writeln!(w, "{}{}", Indent(indent), colors::gray(&line))?;
} }
Ok(()) Ok(())
} }
fn format_class_details( fn format_class(
&self, &self,
w: &mut Formatter<'_>, w: &mut Formatter<'_>,
node: &doc::DocNode, node: &doc::DocNode,
@ -187,7 +138,7 @@ impl<'a> DocPrinter<'a> {
for node in &class_def.constructors { for node in &class_def.constructors {
writeln!(w, "{}{}", Indent(1), node,)?; writeln!(w, "{}{}", Indent(1), node,)?;
if let Some(js_doc) = &node.js_doc { 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| { for node in class_def.properties.iter().filter(|node| {
@ -199,7 +150,7 @@ impl<'a> DocPrinter<'a> {
}) { }) {
writeln!(w, "{}{}", Indent(1), node,)?; writeln!(w, "{}{}", Indent(1), node,)?;
if let Some(js_doc) = &node.js_doc { 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 { for index_sign_def in &class_def.index_signatures {
@ -214,13 +165,13 @@ impl<'a> DocPrinter<'a> {
}) { }) {
writeln!(w, "{}{}", Indent(1), node,)?; writeln!(w, "{}{}", Indent(1), node,)?;
if let Some(js_doc) = &node.js_doc { 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) writeln!(w)
} }
fn format_enum_details( fn format_enum(
&self, &self,
w: &mut Formatter<'_>, w: &mut Formatter<'_>,
node: &doc::DocNode, node: &doc::DocNode,
@ -232,7 +183,7 @@ impl<'a> DocPrinter<'a> {
writeln!(w) writeln!(w)
} }
fn format_interface_details( fn format_interface(
&self, &self,
w: &mut Formatter<'_>, w: &mut Formatter<'_>,
node: &doc::DocNode, node: &doc::DocNode,
@ -242,13 +193,13 @@ impl<'a> DocPrinter<'a> {
for property_def in &interface_def.properties { for property_def in &interface_def.properties {
writeln!(w, "{}{}", Indent(1), property_def)?; writeln!(w, "{}{}", Indent(1), property_def)?;
if let Some(js_doc) = &property_def.js_doc { 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 { for method_def in &interface_def.methods {
writeln!(w, "{}{}", Indent(1), method_def)?; writeln!(w, "{}{}", Indent(1), method_def)?;
if let Some(js_doc) = &method_def.js_doc { 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 { for index_sign_def in &interface_def.index_signatures {
@ -257,7 +208,7 @@ impl<'a> DocPrinter<'a> {
writeln!(w) writeln!(w)
} }
fn format_namespace_details( fn format_namespace(
&self, &self,
w: &mut Formatter<'_>, w: &mut Formatter<'_>,
node: &doc::DocNode, node: &doc::DocNode,
@ -266,7 +217,7 @@ impl<'a> DocPrinter<'a> {
for node in elements { for node in elements {
self.format_signature(w, &node, 1)?; self.format_signature(w, &node, 1)?;
if let Some(js_doc) = &node.js_doc { 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) writeln!(w)

160
cli/doc/tests.rs
View file

@ -44,26 +44,17 @@ impl DocFileLoader for TestLoader {
macro_rules! doc_test { macro_rules! doc_test {
( $name:ident, $source:expr; $block:block ) => { ( $name:ident, $source:expr; $block:block ) => {
doc_test!($name, $source, false, false; $block); doc_test!($name, $source, false; $block);
};
( $name:ident, $source:expr, details; $block:block ) => {
doc_test!($name, $source, true, false; $block);
}; };
( $name:ident, $source:expr, private; $block: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 ) => { ( $name:ident, $source:expr, $private:expr; $block:block ) => {
doc_test!($name, $source, true, true; $block);
};
( $name:ident, $source:expr, $details:expr, $private:expr; $block:block ) => {
#[tokio::test] #[tokio::test]
async fn $name() { async fn $name() {
let source_code = $source; let source_code = $source;
let details = $details;
let private = $private; let private = $private;
let loader = let loader =
@ -73,7 +64,7 @@ macro_rules! doc_test {
.await .await
.unwrap(); .unwrap();
let doc = DocPrinter::new(&entries, details, private).to_string(); let doc = DocPrinter::new(&entries, private).to_string();
#[allow(unused_variables)] #[allow(unused_variables)]
let doc = colors::strip_ansi_codes(&doc); let doc = colors::strip_ansi_codes(&doc);
@ -85,27 +76,17 @@ macro_rules! doc_test {
macro_rules! contains_test { macro_rules! contains_test {
( $name:ident, $source:expr; ( $name:ident, $source:expr;
$( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => { $( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
contains_test!($name, $source, false, false; $($contains),* $(;$($notcontains),*)?); contains_test!($name, $source, false; $($contains),* $(;$($notcontains),*)?);
};
( $name:ident, $source:expr, details;
$( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
contains_test!($name, $source, true, false; $($contains),* $(;$($notcontains),*)?);
}; };
( $name:ident, $source:expr, private; ( $name:ident, $source:expr, private;
$( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => { $( $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:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
contains_test!($name, $source, true, true; $($contains),* $(;$($notcontains),*)?); doc_test!($name, $source, $private; {
};
( $name:ident, $source:expr, $details:expr, $private:expr;
$( $contains:expr ),* $( ; $( $notcontains:expr ),* )? ) => {
doc_test!($name, $source, $details, $private; {
$( $(
assert!(doc.contains($contains)); assert!(doc.contains($contains));
)* )*
@ -128,7 +109,7 @@ macro_rules! json_test {
}; };
( $name:ident, $source:expr, $private:expr; $json:tt ) => { ( $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 actual = serde_json::to_value(&entries).unwrap();
let expected_json = json!($json); let expected_json = json!($json);
assert_eq!(actual, expected_json); assert_eq!(actual, expected_json);
@ -244,7 +225,7 @@ export function fooFn(a: number) {
assert_eq!(actual, expected_json); assert_eq!(actual, expected_json);
assert!(colors::strip_ansi_codes( 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)")); .contains("function fooFn(a: number)"));
} }
@ -1606,8 +1587,7 @@ mod printer {
use super::*; use super::*;
contains_test!(abstract_class, contains_test!(abstract_class,
"export abstract class Class {}", "export abstract class Class {}";
details;
"abstract class Class" "abstract class Class"
); );
@ -1616,8 +1596,7 @@ mod printer {
export abstract class Class { export abstract class Class {
abstract method() {} abstract method() {}
} }
"#, "#;
details;
"abstract method()" "abstract method()"
); );
@ -1626,8 +1605,7 @@ export abstract class Class {
export class Class { export class Class {
async amethod(v) {} async amethod(v) {}
} }
"#, "#;
details;
"async amethod(v)" "async amethod(v)"
); );
@ -1636,22 +1614,18 @@ export class Class {
export class Class { export class Class {
constructor(a, b) {} constructor(a, b) {}
} }
"#, "#;
details;
"constructor(a, b)" "constructor(a, b)"
); );
const CLASS_SOURCE: &str = r#" contains_test!(class_details,
r#"
export class C { export class C {
/** a doc */ /** a doc */
a() {} a() {}
f: number; f: number;
} }
"#; "#;
contains_test!(class_details,
CLASS_SOURCE,
details;
"class C", "class C",
"a()", "a()",
"f: number" "f: number"
@ -1665,7 +1639,6 @@ export class Class {
public pub() {} public pub() {}
} }
"#, "#,
details,
private; private;
"private pri()", "private pri()",
"protected pro()", "protected pro()",
@ -1679,8 +1652,7 @@ export class Class {
protected pro() {} protected pro() {}
public pub() {} public pub() {}
} }
"#, "#;
details;
"protected pro()", "protected pro()",
"pub()" "pub()"
); );
@ -1711,8 +1683,7 @@ export class Class {
get a(): void {} get a(): void {}
set b(_v: void) {} set b(_v: void) {}
} }
"#, "#;
details;
"get a(): void", "get a(): void",
"set b(_v: void)" "set b(_v: void)"
); );
@ -1722,8 +1693,7 @@ export class Class {
export class C { export class C {
[key: string]: number; [key: string]: number;
} }
"#, "#;
details;
"[key: string]: number" "[key: string]: number"
); );
@ -1742,8 +1712,7 @@ export class C {
export class Class { export class Class {
method(v) {} method(v) {}
} }
"#, "#;
details;
"method(v)" "method(v)"
); );
@ -1753,8 +1722,7 @@ export class Class {
someproperty: bool; someproperty: bool;
optproperty: bigint; optproperty: bigint;
} }
"#, "#;
details;
"someproperty: bool", "someproperty: bool",
"optproperty: bigint" "optproperty: bigint"
); );
@ -1764,8 +1732,7 @@ export class Class {
export class C { export class C {
readonly [key: string]: number; readonly [key: string]: number;
} }
"#, "#;
details;
"readonly [key: string]: number" "readonly [key: string]: number"
); );
@ -1774,25 +1741,16 @@ export class C {
export class Class { export class Class {
static property = ""; static property = "";
} }
"#, "#;
details;
"static property" "static property"
); );
contains_test!(class_summary,
CLASS_SOURCE;
"class C";
"a()",
"f: number"
);
contains_test!(class_readonly_property, contains_test!(class_readonly_property,
r#" r#"
export class Class { export class Class {
readonly property = ""; readonly property = "";
} }
"#, "#;
details;
"readonly property" "readonly property"
); );
@ -1802,7 +1760,6 @@ export class Class {
private property = ""; private property = "";
} }
"#, "#,
details,
private; private;
"private property" "private property"
); );
@ -1817,7 +1774,8 @@ export class Class {
"enum Enum" "enum Enum"
); );
const EXPORT_SOURCE: &str = r#" contains_test!(exports_all_with_private,
r#"
export function a() {} export function a() {}
function b() {} function b() {}
export class C {} export class C {}
@ -1826,10 +1784,7 @@ export interface E {}
interface F {} interface F {}
export namespace G {} export namespace G {}
namespace H {} namespace H {}
"#; "#,
contains_test!(exports_all_with_private,
EXPORT_SOURCE,
private; private;
"function a()", "function a()",
"class C", "class C",
@ -1841,18 +1796,6 @@ namespace H {}
"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, contains_test!(function_async,
"export async function a() {}"; "export async function a() {}";
"async function a()" "async function a()"
@ -1952,8 +1895,7 @@ export function f(): Generic<[string, number]> { return {}; }
export interface Interface { export interface Interface {
[index: number]: Interface; [index: number]: Interface;
} }
"#, "#;
details;
"[index: number]: Interface" "[index: number]: Interface"
); );
@ -1963,8 +1905,7 @@ export interface I {
m(a, b); m(a, b);
mo?(c); mo?(c);
} }
"#, "#;
details;
"m(a, b)", "m(a, b)",
"mo?(c)" "mo?(c)"
); );
@ -1975,8 +1916,7 @@ export interface I {
p: string; p: string;
po?: number; po?: number;
} }
"#, "#;
details;
"p: string", "p: string",
"po?: number" "po?: number"
); );
@ -1986,12 +1926,12 @@ export interface I {
export interface Interface { export interface Interface {
readonly [index: number]: Interface; readonly [index: number]: Interface;
} }
"#, "#;
details;
"readonly [index: number]: Interface" "readonly [index: number]: Interface"
); );
const JSDOC_SOURCE: &str = r#" contains_test!(jsdoc,
r#"
/** /**
* A is a class * A is a class
* *
@ -2011,10 +1951,6 @@ export interface B {}
*/ */
export function C() {} export function C() {}
"#; "#;
contains_test!(jsdoc_details,
JSDOC_SOURCE,
details;
"A is a class", "A is a class",
"B is an interface", "B is an interface",
"C is a function", "C is a function",
@ -2023,22 +1959,13 @@ export function C() {}
"Summarised" "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, contains_test!(namespace_declaration,
"export namespace Namespace {}"; "export namespace Namespace {}";
"namespace Namespace" "namespace Namespace"
); );
const NAMESPACE_SOURCE: &str = r#" contains_test!(namespace_details,
r#"
export namespace Namespace { export namespace Namespace {
/** /**
* Doc comment 1 * Doc comment 1
@ -2054,26 +1981,11 @@ export namespace Namespace {
export class B {} export class B {}
} }
"#; "#;
contains_test!(namespace_details,
NAMESPACE_SOURCE,
details;
"namespace Namespace", "namespace Namespace",
"function a()", "function a()",
"class B", "class B",
"Doc comment 1", "Doc comment 1",
"Doc comment 2"; "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";
"Details 1", "Details 1",
"Details 2" "Details 2"
); );

4
cli/main.rs
View file

@ -551,9 +551,9 @@ async fn doc_command(
eprintln!("Node {} was not found!", filter); eprintln!("Node {} was not found!", filter);
std::process::exit(1); std::process::exit(1);
} }
format!("{}", doc::DocPrinter::new(&nodes, true, private)) format!("{}", doc::DocPrinter::new(&nodes, private))
} else { } 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) write_to_stdout_ignore_sigpipe(details.as_bytes()).map_err(ErrBox::from)