Clean up new CLI's help pages (rescript-lang#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"];