fix(flags): move some content from docs.deno.com into help output (#25951)

1 files changed, 78 insertions, 53 deletions

diff --git a/cli/args/flags.rs b/cli/args/flags.rs
index 2cbf46394..b4f566810 100644
--- a/cli/args/flags.rs
+++ b/cli/args/flags.rs
@@ -1258,28 +1258,7 @@ pub fn flags_from_vec(args: Vec<OsString>) -> clap::error::Result<Flags> {
         .get_arguments()
         .any(|arg| arg.get_id().as_str() == "unstable")
     {
-      subcommand = subcommand
-        .mut_arg("unstable", |arg| {
-          let new_help = arg
-            .get_help()
-            .unwrap()
-            .to_string()
-            .split_once("\n")
-            .unwrap()
-            .0
-            .to_string();
-          arg.help_heading(UNSTABLE_HEADING).help(new_help)
-        })
-        .mut_args(|arg| {
-          // long_help here is being used as a metadata, see unstable args definition
-          if arg.get_help_heading() == Some(UNSTABLE_HEADING)
-            && arg.get_long_help().is_some()
-          {
-            arg.hide(false)
-          } else {
-            arg
-          }
-        });
+      subcommand = enable_unstable(subcommand);
     }
 
     help_parse(&mut flags, subcommand);
@@ -1414,6 +1393,31 @@ pub fn flags_from_vec(args: Vec<OsString>) -> clap::error::Result<Flags> {
   Ok(flags)
 }
 
+fn enable_unstable(command: Command) -> Command {
+  command
+    .mut_arg("unstable", |arg| {
+      let new_help = arg
+        .get_help()
+        .unwrap()
+        .to_string()
+        .split_once("\n")
+        .unwrap()
+        .0
+        .to_string();
+      arg.help_heading(UNSTABLE_HEADING).help(new_help)
+    })
+    .mut_args(|arg| {
+      // long_help here is being used as a metadata, see unstable args definition
+      if arg.get_help_heading() == Some(UNSTABLE_HEADING)
+        && arg.get_long_help().is_some()
+      {
+        arg.hide(false)
+      } else {
+        arg
+      }
+    })
+}
+
 macro_rules! heading {
     ($($name:ident = $title:expr),+; $total:literal) => {
       $(const $name: &str = $title;)+
@@ -1852,11 +1856,15 @@ fn compile_subcommand() -> Command {
     "compile",
     cstr!("Compiles the given script into a self contained executable.
 
-  <p(245)>deno compile -A jsr:@std/http/file-server</>
+  <p(245)>deno compile --allow-read --allow-net jsr:@std/http/file-server</>
   <p(245)>deno compile --output file_server jsr:@std/http/file-server</>
 
 Any flags specified which affect runtime behavior will be applied to the resulting binary.
 
+This allows distribution of a Deno application to systems that do not have Deno installed.
+Under the hood, it bundles a slimmed down version of the Deno runtime along with your
+JavaScript or TypeScript code.
+
 Cross-compiling to different target architectures is supported using the <c>--target</> flag.
 On the first invocation with deno will download the proper binary and cache it in <c>$DENO_DIR</>.
 
@@ -2223,6 +2231,9 @@ Supported file types which are behind corresponding unstable flags (see formatti
 Format stdin and write to stdout:
   <p(245)>cat file.ts | deno fmt -</>
 
+Check if the files are formatted:
+  <p(245)>deno fmt --check</>
+
 Ignore formatting code by preceding it with an ignore comment:
   <p(245)>// deno-fmt-ignore</>
 
@@ -2373,7 +2384,7 @@ Ignore formatting a file by adding an ignore comment at the top of the file:
 }
 
 fn init_subcommand() -> Command {
-  command("init", "Initialize a new project", UnstableArgsConfig::None).defer(
+  command("init", "scaffolds a basic Deno project with a script, test, and configuration file", UnstableArgsConfig::None).defer(
     |cmd| {
       cmd
         .arg(Arg::new("dir").value_hint(ValueHint::DirPath))
@@ -2418,7 +2429,7 @@ The following information is shown:
       .arg(
         location_arg()
           .conflicts_with("file")
-          .help("Show files used for origin bound APIs like the Web Storage API when running a script with '--location=<HREF>'")
+          .help(cstr!("Show files used for origin bound APIs like the Web Storage API when running a script with <c>--location=<<HREF>></>"))
       )
       .arg(no_check_arg().hide(true)) // TODO(lucacasonato): remove for 2.0
       .arg(no_config_arg())
@@ -2460,7 +2471,7 @@ If the <bold>--global</> flag is set, installs a script as an executable in the
   <p(245)>deno install --global --allow-net --allow-read jsr:@std/http/file-server</>
   <p(245)>deno install -g https://examples.deno.land/color-logging.ts</>
 
-To change the executable name, use -n/--name:
+To change the executable name, use <c>-n</>/<c>--name</>:
   <p(245)>deno install -g --allow-net --allow-read -n serve jsr:@std/http/file-server</>
 
 The executable name is inferred by default:
@@ -2742,7 +2753,12 @@ To ignore linting on an entire file, you can add an ignore comment at the top of
 }
 
 fn repl_subcommand() -> Command {
-  command("repl", "Read Eval Print Loop", UnstableArgsConfig::ResolutionAndRuntime)
+  command("repl", cstr!(
+    "Starts a read-eval-print-loop, which lets you interactively build up program state in the global context.
+It is especially useful for quick prototyping and checking snippets of code.
+
+TypeScript is supported, however it is not type-checked, only transpiled."
+  ), UnstableArgsConfig::ResolutionAndRuntime)
     .defer(|cmd| runtime_args(cmd, true, true)
       .arg(check_arg(false))
       .arg(
@@ -2825,8 +2841,6 @@ fn serve_subcommand() -> Command {
 
 The serve command uses the default exports of the main module to determine which servers to start.
 
-See https://docs.deno.com/runtime/manual/tools/serve for more detailed information.
-
 Start a server defined in server.ts:
   <p(245)>deno serve server.ts</>
 
@@ -2837,7 +2851,7 @@ Start a server defined in server.ts, watching for changes and running on port 50
     .arg(
       Arg::new("port")
         .long("port")
-        .help("The TCP port to serve on, defaulting to 8000. Pass 0 to pick a random free port")
+        .help(cstr!("The TCP port to serve on. Pass 0 to pick a random free port <p(245)>[default: 8000]</>"))
         .value_parser(value_parser!(u16)),
     )
     .arg(
@@ -3047,11 +3061,13 @@ fn parallel_arg(descr: &str) -> Arg {
 fn types_subcommand() -> Command {
   command(
     "types",
-    "Print runtime TypeScript declarations.
+    cstr!(
+      "Print runtime TypeScript declarations.
 
   <p(245)>deno types > lib.deno.d.ts</>
 
-The declaration file could be saved and used for typing information.",
+The declaration file could be saved and used for typing information."
+    ),
     UnstableArgsConfig::None,
   )
 }
@@ -3161,7 +3177,7 @@ See the Deno 1.x to 2.x Migration Guide for migration instructions: https://docs
 }
 
 fn publish_subcommand() -> Command {
-  command("publish", "Publish the current working directory's package or workspace", UnstableArgsConfig::ResolutionOnly)
+  command("publish", "Publish the current working directory's package or workspace to JSR", UnstableArgsConfig::ResolutionOnly)
     .defer(|cmd| {
       cmd
       .arg(
@@ -3550,8 +3566,7 @@ fn permission_args(app: Command, requires: Option<&'static str>) -> Command {
           .long("allow-hrtime")
           .action(ArgAction::SetTrue)
           .help("REMOVED in Deno 2.0")
-          .hide(true)
-          ;
+          .hide(true);
         if let Some(requires) = requires {
           arg = arg.requires(requires)
         }
@@ -3564,8 +3579,7 @@ fn permission_args(app: Command, requires: Option<&'static str>) -> Command {
           .long("deny-hrtime")
           .action(ArgAction::SetTrue)
           .help("REMOVED in Deno 2.0")
-          .hide(true)
-          ;
+          .hide(true);
         if let Some(requires) = requires {
           arg = arg.requires(requires)
         }
@@ -3801,7 +3815,9 @@ fn location_arg() -> Arg {
       url.set_password(None).unwrap();
       Ok(url)
     })
-    .help("Value of 'globalThis.location' used by some web APIs")
+    .help(cstr!(
+      "Value of <p(245)>globalThis.location</> used by some web APIs"
+    ))
     .value_hint(ValueHint::Url)
 }
 
@@ -4655,7 +4671,7 @@ fn json_reference_parse(
   app.build();
 
   fn serialize_command(
-    command: &mut Command,
+    mut command: Command,
     top_level: bool,
   ) -> deno_core::serde_json::Value {
     let args = command
@@ -4663,7 +4679,7 @@ fn json_reference_parse(
       .filter(|arg| {
         !arg.is_hide_set()
           && if top_level {
-            true
+            arg.is_global_set()
           } else {
             !arg.is_global_set()
           }
@@ -4672,40 +4688,49 @@ fn json_reference_parse(
         let name = arg.get_id().as_str();
         let short = arg.get_short();
         let long = arg.get_long();
-        let aliases = arg.get_visible_aliases();
         let required = arg.is_required_set();
-        let help = arg.get_help().map(|help| help.to_string());
+        let help = arg.get_help().map(|help| help.ansi().to_string());
+        let help_heading = arg
+          .get_help_heading()
+          .map(|help_heading| help_heading.to_string());
         let usage = arg.to_string();
 
         json!({
           "name": name,
           "short": short,
           "long": long,
-          "aliases": aliases,
           "required": required,
           "help": help,
+          "help_heading": help_heading,
           "usage": usage,
         })
       })
       .collect::<Vec<_>>();
 
     let name = command.get_name().to_string();
-    let about = command.get_about().map(|about| about.to_string());
-    let visible_aliases = command
-      .get_visible_aliases()
-      .map(|s| s.to_string())
-      .collect::<Vec<_>>();
-    let usage = command.render_usage().to_string();
+    let about = command.get_about().map(|about| about.ansi().to_string());
+    let usage = command.render_usage().ansi().to_string();
 
     let subcommands = command
-      .get_subcommands_mut()
-      .map(|command| serialize_command(command, false))
+      .get_subcommands()
+      .map(|command| {
+        serialize_command(
+          if command
+            .get_arguments()
+            .any(|arg| arg.get_id().as_str() == "unstable")
+          {
+            enable_unstable(command.clone())
+          } else {
+            command.clone()
+          },
+          false,
+        )
+      })
       .collect::<Vec<_>>();
 
     json!({
       "name": name,
       "about": about,
-      "visible_aliases": visible_aliases,
       "args": args,
       "subcommands": subcommands,
       "usage": usage,
@@ -4713,7 +4738,7 @@ fn json_reference_parse(
   }
 
   flags.subcommand = DenoSubcommand::JSONReference(JSONReferenceFlags {
-    json: serialize_command(&mut app, true),
+    json: serialize_command(app, true),
   })
 }