From 9ec18c35c7e6207fc96d6b2508c3bf37953c4f93 Mon Sep 17 00:00:00 2001 From: David Sherret Date: Thu, 26 Oct 2023 21:27:50 -0400 Subject: [PATCH] feat(doc): display non-exported types referenced in exported types (#20990) Upgrades to deno_doc 0.70 which includes the feature for showing non-exported types referenced in exported types as well as a much more advanced deno doc that uses a symbol graph. --- Cargo.lock | 9 ++-- cli/Cargo.toml | 4 +- cli/tests/integration/doc_tests.rs | 5 ++ .../testdata/doc/referenced_private_types.out | 12 +++++ .../testdata/doc/referenced_private_types.ts | 7 +++ cli/tools/doc.rs | 54 ++++++++----------- 6 files changed, 52 insertions(+), 39 deletions(-) create mode 100644 cli/tests/testdata/doc/referenced_private_types.out create mode 100644 cli/tests/testdata/doc/referenced_private_types.ts diff --git a/Cargo.lock b/Cargo.lock index 42c5108b47..1fcfb8b9b2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1265,10 +1265,11 @@ dependencies = [ [[package]] name = "deno_doc" -version = "0.69.2" +version = "0.70.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6932fbb8bcd9154b8b3b6453dadd812999808aeaa5bfe01a2c63d075b8ad3866" +checksum = "1dd0a46bf024da1e3a1caa7fbb6309bd2abd5395c738b73efe34276a6d9b9838" dependencies = [ + "anyhow", "cfg-if 1.0.0", "deno_ast", "deno_graph", @@ -1350,9 +1351,9 @@ dependencies = [ [[package]] name = "deno_graph" -version = "0.59.0" +version = "0.59.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8863c48f0d7c03beef9a64173557d5ba8e32a4a3f1b8830420c6ec47668fa4c6" +checksum = "ede5d554aca4ac11a25f70b59e80cc1f1fe2cb134664fa33972cf9527f0582bc" dependencies = [ "anyhow", "async-trait", diff --git a/cli/Cargo.toml b/cli/Cargo.toml index 17167a0d63..b6547c2b3d 100644 --- a/cli/Cargo.toml +++ b/cli/Cargo.toml @@ -49,9 +49,9 @@ deno_ast = { workspace = true, features = ["bundler", "cjs", "codegen", "dep_gra deno_cache_dir = "=0.6.0" deno_config = "=0.4.0" deno_core = { workspace = true, features = ["include_js_files_for_snapshotting"] } -deno_doc = "=0.69.2" +deno_doc = "=0.70.0" deno_emit = "=0.31.1" -deno_graph = "=0.59.0" +deno_graph = "=0.59.1" deno_lint = { version = "=0.52.2", features = ["docs"] } deno_lockfile.workspace = true deno_npm = "0.15.2" diff --git a/cli/tests/integration/doc_tests.rs b/cli/tests/integration/doc_tests.rs index 72f5f43140..cdbee845b2 100644 --- a/cli/tests/integration/doc_tests.rs +++ b/cli/tests/integration/doc_tests.rs @@ -47,6 +47,11 @@ itest!(deno_doc_types_header { http_server: true, }); +itest!(deno_doc_referenced_private_types { + args: "doc doc/referenced_private_types.ts", + output: "doc/referenced_private_types.out", +}); + itest!(_060_deno_doc_displays_all_overloads_in_details_view { args: "doc doc/060_deno_doc_displays_all_overloads_in_details_view.ts NS.test", diff --git a/cli/tests/testdata/doc/referenced_private_types.out b/cli/tests/testdata/doc/referenced_private_types.out new file mode 100644 index 0000000000..507b91e3ab --- /dev/null +++ b/cli/tests/testdata/doc/referenced_private_types.out @@ -0,0 +1,12 @@ +Defined in file:///[WILDCARD]/doc/referenced_private_types.ts:5:0 + +class MyClass + + prop: MyInterface + +Defined in file:///[WILDCARD]/doc/referenced_private_types.ts:1:0 + +private interface MyInterface + + prop?: string + diff --git a/cli/tests/testdata/doc/referenced_private_types.ts b/cli/tests/testdata/doc/referenced_private_types.ts new file mode 100644 index 0000000000..9570d46254 --- /dev/null +++ b/cli/tests/testdata/doc/referenced_private_types.ts @@ -0,0 +1,7 @@ +interface MyInterface { + prop?: string; +} + +export class MyClass { + prop: MyInterface = {}; +} diff --git a/cli/tools/doc.rs b/cli/tools/doc.rs index 66fb3bfd5d..1a770b2d3a 100644 --- a/cli/tools/doc.rs +++ b/cli/tools/doc.rs @@ -7,15 +7,15 @@ use crate::colors; use crate::display::write_json_to_stdout; use crate::display::write_to_stdout_ignore_sigpipe; use crate::factory::CliFactory; -use crate::file_fetcher::File; use crate::graph_util::graph_lock_or_exit; +use crate::graph_util::CreateGraphOptions; use crate::tsc::get_types_declaration_file_text; -use deno_ast::MediaType; use deno_core::anyhow::bail; use deno_core::error::AnyError; -use deno_core::resolve_path; use deno_core::resolve_url_or_path; use deno_doc as doc; +use deno_graph::CapturingModuleParser; +use deno_graph::DefaultParsedSourceStore; use deno_graph::GraphKind; use deno_graph::ModuleSpecifier; @@ -25,6 +25,13 @@ pub async fn print_docs( ) -> Result<(), AnyError> { let factory = CliFactory::from_flags(flags).await?; let cli_options = factory.cli_options(); + let module_info_cache = factory.module_info_cache()?; + let source_parser = deno_graph::DefaultModuleParser::new_for_analysis(); + let store = DefaultParsedSourceStore::default(); + let analyzer = + module_info_cache.as_module_analyzer(Some(&source_parser), &store); + let capturing_parser = + CapturingModuleParser::new(Some(&source_parser), &store); let mut doc_nodes = match doc_flags.source_file { DocSourceFileFlag::Builtin => { @@ -42,7 +49,6 @@ pub async fn print_docs( )], Vec::new(), ); - let analyzer = deno_graph::CapturingModuleAnalyzer::default(); let mut graph = deno_graph::ModuleGraph::new(GraphKind::TypesOnly); graph .build( @@ -54,51 +60,33 @@ pub async fn print_docs( }, ) .await; - let doc_parser = doc::DocParser::new( - graph, - doc_flags.private, - analyzer.as_capturing_parser(), - ); + let doc_parser = + doc::DocParser::new(&graph, doc_flags.private, capturing_parser)?; doc_parser.parse_module(&source_file_specifier)?.definitions } DocSourceFileFlag::Path(source_file) => { - let file_fetcher = factory.file_fetcher()?; let module_graph_builder = factory.module_graph_builder().await?; let maybe_lockfile = factory.maybe_lockfile(); - let parsed_source_cache = factory.parsed_source_cache(); let module_specifier = resolve_url_or_path(&source_file, cli_options.initial_cwd())?; - // If the root module has external types, the module graph won't redirect it, - // so instead create a dummy file which exports everything from the actual file being documented. - let root_specifier = - resolve_path("./$deno$doc.ts", cli_options.initial_cwd()).unwrap(); - let root = File { - maybe_types: None, - media_type: MediaType::TypeScript, - source: format!("export * from \"{module_specifier}\";").into(), - specifier: root_specifier.clone(), - maybe_headers: None, - }; - - // Save our fake file into file fetcher cache. - file_fetcher.insert_cached(root); - + let mut loader = module_graph_builder.create_graph_loader(); let graph = module_graph_builder - .create_graph(GraphKind::TypesOnly, vec![root_specifier.clone()]) + .create_graph_with_options(CreateGraphOptions { + graph_kind: GraphKind::TypesOnly, + roots: vec![module_specifier.clone()], + loader: &mut loader, + analyzer: &analyzer, + }) .await?; if let Some(lockfile) = maybe_lockfile { graph_lock_or_exit(&graph, &mut lockfile.lock()); } - let doc_parser = doc::DocParser::new( - graph, - doc_flags.private, - parsed_source_cache.as_capturing_parser(), - ); - doc_parser.parse_with_reexports(&root_specifier)? + doc::DocParser::new(&graph, doc_flags.private, capturing_parser)? + .parse_with_reexports(&module_specifier)? } };