feat(cli/doc): Support doc for runtime built-ins (#4635)

cli/doc/parser.rs

@@ -184,6 +184,14 @@ impl DocParser {
   pub async fn parse(&self, file_name: &str) -> Result<Vec<DocNode>, ErrBox> {
     let source_code = self.loader.load_source_code(file_name).await?;
 
+    self.parse_source(file_name, source_code.as_str())
+  }
+
+  pub fn parse_source(
+    &self,
+    file_name: &str,
+    source_code: &str,
+  ) -> Result<Vec<DocNode>, ErrBox> {
     let module_doc = self.parse_module(file_name, &source_code)?;
     Ok(module_doc.exports)
   }

cli/flags.rs

@@ -34,7 +34,7 @@ pub enum DenoSubcommand {
   },
   Doc {
     json: bool,
-    source_file: String,
+    source_file: Option<String>,
     filter: Option<String>,
   },
   Eval {
@@ -566,7 +566,7 @@ fn upgrade_parse(flags: &mut Flags, matches: &clap::ArgMatches) {
 
 fn doc_parse(flags: &mut Flags, matches: &clap::ArgMatches) {
   reload_arg_parse(flags, matches);
-  let source_file = matches.value_of("source_file").map(String::from).unwrap();
+  let source_file = matches.value_of("source_file").map(String::from);
   let json = matches.is_present("json");
   let filter = matches.value_of("filter").map(String::from);
   flags.subcommand = DenoSubcommand::Doc {
@@ -581,7 +581,7 @@ fn types_subcommand<'a, 'b>() -> App<'a, 'b> {
     .about("Print runtime TypeScript declarations")
     .long_about(
       "Print runtime TypeScript declarations.
-  deno types > lib.deno_runtime.d.ts
+  deno types > lib.deno.d.ts
 
 The declaration file could be saved and used for typing information.",
     )
@@ -799,18 +799,22 @@ and is used to replace the current executable.",
 
 fn doc_subcommand<'a, 'b>() -> App<'a, 'b> {
   SubCommand::with_name("doc")
-    .about("Show documentation for module")
+    .about("Show documentation for a module")
     .long_about(
-      "Show documentation for module.
+      "Show documentation for a module.
 
-Output documentation to terminal:
+Output documentation to standard output:
     deno doc ./path/to/module.ts
 
-Show detail of symbol:
+Output documentation in JSON format:
+    deno doc --json ./path/to/module.ts
+
+Target a specific symbol:
     deno doc ./path/to/module.ts MyClass.someField
 
-Output documentation in JSON format:
-    deno doc --json ./path/to/module.ts",
+Show documentation for runtime built-ins:
+    deno doc
+    deno doc --builtin Deno.Listener",
     )
     .arg(reload_arg())
     .arg(
@@ -819,11 +823,12 @@ Output documentation in JSON format:
         .help("Output documentation in JSON format.")
         .takes_value(false),
     )
-    .arg(
-      Arg::with_name("source_file")
-        .takes_value(true)
-        .required(true),
-    )
+    // TODO(nayeemrmn): Make `--builtin` a proper option. Blocked by
+    // https://github.com/clap-rs/clap/issues/1794. Currently `--builtin` is
+    // just a possible value of `source_file` so leading hyphens must be
+    // enabled.
+    .setting(clap::AppSettings::AllowLeadingHyphen)
+    .arg(Arg::with_name("source_file").takes_value(true))
     .arg(
       Arg::with_name("filter")
         .help("Dot separated path to symbol.")
@@ -2534,7 +2539,7 @@ mod tests {
       Flags {
         subcommand: DenoSubcommand::Doc {
           json: true,
-          source_file: "path/to/module.ts".to_string(),
+          source_file: Some("path/to/module.ts".to_string()),
           filter: None,
         },
         ..Flags::default()
@@ -2552,12 +2557,39 @@ mod tests {
       Flags {
         subcommand: DenoSubcommand::Doc {
           json: false,
-          source_file: "path/to/module.ts".to_string(),
+          source_file: Some("path/to/module.ts".to_string()),
           filter: Some("SomeClass.someField".to_string()),
         },
         ..Flags::default()
       }
     );
+
+    let r = flags_from_vec_safe(svec!["deno", "doc"]);
+    assert_eq!(
+      r.unwrap(),
+      Flags {
+        subcommand: DenoSubcommand::Doc {
+          json: false,
+          source_file: None,
+          filter: None,
+        },
+        ..Flags::default()
+      }
+    );
+
+    let r =
+      flags_from_vec_safe(svec!["deno", "doc", "--builtin", "Deno.Listener"]);
+    assert_eq!(
+      r.unwrap(),
+      Flags {
+        subcommand: DenoSubcommand::Doc {
+          json: false,
+          source_file: Some("--builtin".to_string()),
+          filter: Some("Deno.Listener".to_string()),
+        },
+        ..Flags::default()
+      }
+    );
   }
 
   #[test]

cli/js/globals.ts

@@ -25,7 +25,7 @@ import * as streams from "./web/streams/mod.ts";
 import { core } from "./core.ts";
 
 // This global augmentation is just enough types to be able to build Deno,
-// the runtime types are fully defined in `lib.deno_runtime.d.ts`.
+// the runtime types are fully defined in `lib.deno.*.d.ts`.
 declare global {
   interface CallSite {
     getThis(): unknown;

cli/lib.rs

@@ -251,6 +251,15 @@ async fn print_file_info(
   Ok(())
 }
 
+fn get_types() -> String {
+  format!(
+    "{}\n{}\n{}",
+    crate::js::DENO_NS_LIB,
+    crate::js::SHARED_GLOBALS_LIB,
+    crate::js::WINDOW_LIB
+  )
+}
+
 async fn info_command(
   flags: Flags,
   file: Option<String>,
@@ -369,13 +378,12 @@ async fn bundle_command(
 
 async fn doc_command(
   flags: Flags,
-  source_file: String,
+  source_file: Option<String>,
   json: bool,
   maybe_filter: Option<String>,
 ) -> Result<(), ErrBox> {
   let global_state = GlobalState::new(flags.clone())?;
-  let module_specifier =
-    ModuleSpecifier::resolve_url_or_path(&source_file).unwrap();
+  let source_file = source_file.unwrap_or_else(|| "--builtin".to_string());
 
   impl DocFileLoader for SourceFileFetcher {
     fn load_source_code(
@@ -397,9 +405,16 @@ async fn doc_command(
 
   let loader = Box::new(global_state.file_fetcher.clone());
   let doc_parser = doc::DocParser::new(loader);
-  let parse_result = doc_parser
-    .parse_with_reexports(&module_specifier.to_string())
-    .await;
+
+  let parse_result = if source_file == "--builtin" {
+    doc_parser.parse_source("lib.deno.d.ts", get_types().as_str())
+  } else {
+    let module_specifier =
+      ModuleSpecifier::resolve_url_or_path(&source_file).unwrap();
+    doc_parser
+      .parse_with_reexports(&module_specifier.to_string())
+      .await
+  };
 
   let doc_nodes = match parse_result {
     Ok(nodes) => nodes,
@@ -580,12 +595,7 @@ pub fn main() {
       return;
     }
     DenoSubcommand::Types => {
-      let types = format!(
-        "{}\n{}\n{}",
-        crate::js::DENO_NS_LIB,
-        crate::js::SHARED_GLOBALS_LIB,
-        crate::js::WINDOW_LIB
-      );
+      let types = get_types();
       if let Err(e) = write_to_stdout_ignore_sigpipe(types.as_bytes()) {
         eprintln!("{}", e);
         std::process::exit(1);