Clean up new CLI's help pages (#5135)

Author: chenglou

jscomp/main/rescript_main.ml

@@ -85,12 +85,11 @@ let ninja_command_exit (type t) (ninja_args : string array) : t =
  What will happen, some flags are really not good
  ninja -C _build
 *)
-let clean_usage = "Usage : rescript.exe clean <options>\n\
- It only clean the current project by default"
-let build_usage = "Usage : rescript.exe build <options> -- <ninja_options>\n\
- It only builds the current project by default\n\
- For ninja options, try rescript.exe -- -h. \n\
- Note they are supposed to be internals and not reliable."
+let clean_usage = "Usage: rescript.exe clean <options>\n\n\
+ `rescript clean` only cleans the current project\n"
+let build_usage = "Usage: rescript.exe build <options> -- <ninja_options>\n\n\
+ `rescript build` implicitly builds dependencies if they aren't built\n\n\
+ `rescript.exe -- -h` for Ninja options (internal usage only; unstable)\n"
 
 
 
@@ -138,14 +137,14 @@ let build_subcommand ~start argv argv_len =
  "-w", unit_set_spec watch_mode, 
  "Watch mode";
  "-with-deps", unit_set_spec make_world,
- "Build with deps";
+ "Build dependencies explicitly";
  "-install", unit_set_spec do_install,
  "*internal* Install public interface files for dependencies ";
  (* This should be put in a subcommand
  previously it works with the implication `bsb && bsb -install`
  *)
  "-ws", string_set_spec (ref ""),
- "[host]:port set the host, port for websocket build notifications";
+ "[host]:port set up host & port for WebSocket build notifications";
  "-regen", unit_set_spec force_regenerate,
  "*internal* \n\
  Always regenerate build.ninja no matter bsconfig.json is changed or not";
@@ -184,14 +183,14 @@ let clean_subcommand ~start argv =
  Bsb_arg.parse_exn 
  ~usage:clean_usage ~start ~argv [|
  "-with-deps", unit_set_spec make_world,
- "clean its deps too"
+ "Clean dependencies too"
  |] failed_annon;
  if !make_world then 
  Bsb_clean.clean_bs_deps Bsb_global_paths.cwd ; 
  Bsb_clean.clean_self Bsb_global_paths.cwd 
 let init_usage = "Init the project\n\
  rescript init [project-name]\n\
- defaults to the current directory if not set\n\
+ defaults to the current directory if [project-name] isn't set\n\
  "
 let init_subcommand ~start argv = 
  Bsb_arg.parse_exn 

lib/4.06.1/rescript.ml

@@ -16662,12 +16662,11 @@ let ninja_command_exit (type t) (ninja_args : string array) : t =
  What will happen, some flags are really not good
  ninja -C _build
 *)
-let clean_usage = "Usage : rescript.exe clean <options>\n\
- It only clean the current project by default"
-let build_usage = "Usage : rescript.exe build <options> -- <ninja_options>\n\
- It only builds the current project by default\n\
- For ninja options, try rescript.exe -- -h. \n\
- Note they are supposed to be internals and not reliable."
+let clean_usage = "Usage: rescript.exe clean <options>\n\n\
+ `rescript clean` only cleans the current project\n"
+let build_usage = "Usage: rescript.exe build <options> -- <ninja_options>\n\n\
+ `rescript build` implicitly builds dependencies if they aren't built\n\n\
+ `rescript.exe -- -h` for Ninja options (internal usage only; unstable)\n"
 
 
 
@@ -16715,14 +16714,14 @@ let build_subcommand ~start argv argv_len =
  "-w", unit_set_spec watch_mode, 
  "Watch mode";
  "-with-deps", unit_set_spec make_world,
- "Build with deps";
+ "Build dependencies explicitly";
  "-install", unit_set_spec do_install,
  "*internal* Install public interface files for dependencies ";
  (* This should be put in a subcommand
  previously it works with the implication `bsb && bsb -install`
  *)
  "-ws", string_set_spec (ref ""),
- "[host]:port set the host, port for websocket build notifications";
+ "[host]:port set up host & port for WebSocket build notifications";
  "-regen", unit_set_spec force_regenerate,
  "*internal* \n\
  Always regenerate build.ninja no matter bsconfig.json is changed or not";
@@ -16761,14 +16760,14 @@ let clean_subcommand ~start argv =
  Bsb_arg.parse_exn 
  ~usage:clean_usage ~start ~argv [|
  "-with-deps", unit_set_spec make_world,
- "clean its deps too"
+ "Clean dependencies too"
  |] failed_annon;
  if !make_world then 
  Bsb_clean.clean_bs_deps Bsb_global_paths.cwd ; 
  Bsb_clean.clean_self Bsb_global_paths.cwd 
 let init_usage = "Init the project\n\
  rescript init [project-name]\n\
- defaults to the current directory if not set\n\
+ defaults to the current directory if [project-name] isn't set\n\
  "
 let init_subcommand ~start argv = 
  Bsb_arg.parse_exn 

rescript

@@ -125,7 +125,7 @@ function setUpWebSocket() {
  // @ts-ignore
  if (err !== undefined && err.code === "EADDRINUSE") {
  var error = std_is_tty ? `\x1b[1;31mERROR:\x1b[0m` : `ERROR:`;
- console.error(`${error} The websocket port number ${webSocketPort} is in use. 
+ console.error(`${error} The websocket port number ${webSocketPort} is in use.
 Please pick a different one using the \`-ws [host:]port\` flag from bsb.`);
  } else {
  console.error(err);
@@ -149,21 +149,24 @@ if (process.env.NINJA_ANSI_FORCED === undefined) {
  dlog(`NINJA_ANSI_FORCED: "${process.env.NINJA_ANSI_FORCED}"`);
 }
 function help() {
- console.log(`Available flags
--v, -version display version number
--h, -help display help 
+ console.log(`Usage: rescript <options> <subcommand>
+
+\`rescript\` is equivalent to \`rescript build\`
+
+Options:
+ -v, -version display version number
+ -h, -help display help
+
 Subcommands:
- build 
- clean
- format
- convert
- help
-Run rescript subcommand -h for more details,
-For example:
- rescript build -h
- rescript format -h
-The default \`rescript\` is equivalent to \`rescript build\` subcommand
- `);
+ build
+ clean
+ format
+ convert
+ help
+
+Run \`rescript <subcommand> -h\` for subcommand help. Examples:
+ rescript build -h
+ rescript format -h`);
 }
 
 var maybe_subcommand = process_argv[2];
@@ -530,7 +533,7 @@ if (
  // helps avoid redundant build, but this will
  // save the event loop call `setImmediate`
  return;
- } 
+ }
  if (validEvent(event, reason)) {
  dlog(`\nEvent ${event} ${reason}`);
  LAST_FIRED_EVENT = event_time;

scripts/rescript_arg.js

@@ -38,15 +38,16 @@ function usage_b(b, usage, specs) {
  b.add(usage);
  b.add(`\nOptions:\n`);
  if(specs.length === 0){
- return 
+ return
  }
  var max_col = 0;
  for (let [key] of specs) {
  if (key.length > max_col) {
  max_col = key.length;
  }
  }
- for (let [key, _, doc] of specs) {
+ for (let i = 0; i < specs.length; i++) {
+ let [key, _, doc] = specs[i]
  if (!doc.startsWith("*internal*")) {
  b.add(" ")
  .add(key)
@@ -66,7 +67,9 @@ function usage_b(b, usage, specs) {
  cur = i + 1;
  }
  }
- b.add("\n");
+ if (i < specs.length - 1) {
+ b.add("\n");
+ }
  }
  }
 }

scripts/rescript_convert.js

@@ -1,9 +1,11 @@
 //@ts-check
 var arg = require("./rescript_arg.js");
 var format_usage = `Usage: rescript convert <options> [files]
-rescript convert -- it converts the current directory
-Note this subcommand will remove old reason/ml files and 
-create new ReScript files, make sure your work is saved first.
+
+\`rescript convert\` converts the current directory
+
+**This command removes old Reason/OCaml files and creates new ReScript 
+files. Make sure your work is saved first!**
 `;
 
 var child_process = require("child_process");
@@ -22,7 +24,7 @@ var specs = [
  [
  "-all",
  { kind: "Unit", data: { kind: "Unit_set", data: formatProject } },
- "Formatting the whole project ",
+ "Convert the whole project",
  ],
 ];
 

scripts/rescript_format.js

@@ -1,7 +1,8 @@
 //@ts-check
 var arg = require("./rescript_arg.js");
 var format_usage = `Usage: rescript format <options> [files]
-rescript format -- it format the current directory
+
+\`rescript format\` formats the current directory
 `;
 var child_process = require("child_process");
 var path = require("path");
@@ -23,14 +24,14 @@ var specs = [
  [
  "-stdin",
  { kind: "String", data: { kind: "String_set", data: stdin } },
- `[.res|.resi|.ml|.mli|.re|.rei] Read the format code from stdin and print the formatted code
-in the stdout (in rescript syntax)`,
+ `[.res|.resi|.ml|.mli|.re|.rei] Read the code from stdin and print
+the formatted code to stdout in ReScript syntax`,
  ],
  // ml|mli
  [
  "-all",
  { kind: "Unit", data: { kind: "Unit_set", data: format } },
- "Formatting the whole project ",
+ "Format the whole project ",
  ],
 ];
 var formattedStdExtensions = [".res", ".resi", ".ml", ".mli", ".re", ".rei"];