Tweak the help message and comments

README.md

@@ -33,7 +33,7 @@ Commands:
   generate-build-matrix  Generate build matrix for benchmarking (legacy feature)
   upgrade                Upgrade toolchains
   shell-completion       Generate shell completion for bash/elvish/fish/pwsh/zsh to stdout
-  version                Print version info and exit
+  version                Print version information and exit
   help                   Print this message or the help of the given subcommand(s)
 
 Options:
@@ -46,7 +46,7 @@ Common Options:
   -v, --verbose                  Increase verbosity
       --trace                    Trace the execution of the program
       --dry-run                  Do not actually run the command
-      --build-graph              generate build graph
+      --build-graph              Generate build graph
 ```
 
 See tutorials at

crates/moon/src/cli.rs

@@ -93,7 +93,7 @@ pub enum MoonBuildSubcommands {
     Run(RunSubcommand),
     Test(TestSubcommand),
     #[clap(hide = true)]
-    GenerateTestDriver(GeneratedTestDriverSubcommand),
+    GenerateTestDriver(GenerateTestDriverSubcommand),
     Clean(CleanSubcommand),
     Fmt(FmtSubcommand),
     Doc(DocSubcommand),
@@ -144,6 +144,7 @@ pub struct BuildFlags {
     #[clap(skip)]
     pub target_backend: Option<TargetBackend>,
 
+    /// Handle the selected targets sequentially
     #[clap(long, requires = "target")]
     pub serial: bool,
 
@@ -160,11 +161,11 @@ pub struct BuildFlags {
     #[clap(long)]
     pub output_wat: bool,
 
-    /// treat all warnings as errors
+    /// Treat all warnings as errors
     #[clap(long, short)]
     pub deny_warn: bool,
 
-    /// don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
+    /// Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
     #[clap(long)]
     pub no_render: bool,
 }

crates/moon/src/cli/build_matrix.rs

@@ -45,6 +45,7 @@ pub struct GenerateBuildMatrix {
     #[clap(long, long = "mcol")]
     pub mod_cols: Option<u32>,
 
+    /// The output directory
     #[clap(long, long = "output-dir", short, short = 'o')]
     pub out_dir: PathBuf,
 }

crates/moon/src/cli/check.rs

@@ -42,19 +42,19 @@ use super::{get_compiler_flags, BuildFlags};
 /// Check the current package, but don't build object files
 #[derive(Debug, clap::Parser, Clone)]
 pub struct CheckSubcommand {
-    /// Monitor the file system and automatically check files
-    #[clap(long, short)]
-    pub watch: bool,
-
     #[clap(flatten)]
     pub build_flags: BuildFlags,
 
-    /// output in json format
+    /// Output in json format
     #[clap(long)]
     pub output_json: bool,
 
     #[clap(flatten)]
     pub auto_sync_flags: AutoSyncFlags,
+
+    /// Monitor the file system and automatically check files
+    #[clap(long, short)]
+    pub watch: bool,
 }
 
 pub fn run_check(cli: &UniversalFlags, cmd: &CheckSubcommand) -> anyhow::Result<i32> {

crates/moon/src/cli/doc.rs

@@ -36,10 +36,12 @@ pub struct DocSubcommand {
     #[clap(long)]
     pub serve: bool,
 
-    #[clap(long, short, default_value = "127.0.0.1")]
+    /// The address of the server
+    #[clap(long, short, default_value = "127.0.0.1", requires("serve"))]
     pub bind: String,
 
-    #[clap(long, short, default_value = "3000")]
+    /// The port of the server
+    #[clap(long, short, default_value = "3000", requires("serve"))]
     pub port: u16,
 
     #[clap(flatten)]

crates/moon/src/cli/fmt.rs

@@ -29,9 +29,11 @@ use super::UniversalFlags;
 /// Format source code
 #[derive(Debug, clap::Parser)]
 pub struct FmtSubcommand {
+    /// Check only and don't change the source code
     #[clap(long)]
     check: bool,
 
+    /// Sort input files
     #[clap(long)]
     pub sort_input: bool,
 }

crates/moon/src/cli/generate_test_driver.rs

@@ -32,15 +32,17 @@ use moonutil::mooncakes::RegistryConfig;
 use std::io::{Read, Write};
 use std::path::{Path, PathBuf};
 
-/// Test the current package
+/// Generate tests for the provided packages
 #[derive(Debug, clap::Parser)]
-pub struct GeneratedTestDriverSubcommand {
+pub struct GenerateTestDriverSubcommand {
     #[clap(flatten)]
     pub build_flags: BuildFlags,
 
+    /// The paths of the packages
     #[clap(short, long, num_args(0..))]
     pub package: Option<Vec<PathBuf>>,
 
+    /// The test driver kind
     #[clap(long)]
     pub driver_kind: DriverKind,
 }
@@ -98,7 +100,7 @@ fn moonc_gen_test_info(files: &[PathBuf], target_dir: &Path) -> anyhow::Result<S
 
 pub fn generate_test_driver(
     cli: UniversalFlags,
-    cmd: GeneratedTestDriverSubcommand,
+    cmd: GenerateTestDriverSubcommand,
 ) -> anyhow::Result<i32> {
     let PackageDirs {
         source_dir,

crates/moon/src/cli/run.rs

@@ -47,11 +47,13 @@ pub struct RunSubcommand {
     #[clap(flatten)]
     pub build_flags: BuildFlags,
 
+    /// The arguments provided to the program to be run
+    pub args: Vec<String>,
+
     #[clap(flatten)]
     pub auto_sync_flags: AutoSyncFlags,
 
-    pub args: Vec<String>,
-
+    /// Only build, do not run the code
     #[clap(long)]
     pub build_only: bool,
 }

crates/moon/src/cli/test.rs

@@ -62,10 +62,6 @@ pub struct TestSubcommand {
     #[clap(short, long, requires("file"))]
     pub index: Option<u32>,
 
-    /// Only build, do not run the tests
-    #[clap(long)]
-    pub build_only: bool,
-
     /// Update the test snapshot
     #[clap(short, long)]
     pub update: bool,
@@ -77,9 +73,15 @@ pub struct TestSubcommand {
     #[clap(flatten)]
     pub auto_sync_flags: AutoSyncFlags,
 
+    /// Only build, do not run the tests
+    #[clap(long)]
+    pub build_only: bool,
+
+    /// Run the tests in a target backend sequentially
     #[clap(long)]
     pub no_parallelize: bool,
 
+    /// Print failure message in JSON format
     #[clap(long)]
     pub test_failure_json: bool,
 }

crates/moon/src/cli/tool/format_and_diff.rs

@@ -18,10 +18,14 @@
 
 use std::{io::BufRead, path::PathBuf, process::Stdio};
 
+/// Format the code and print the difference
 #[derive(Debug, clap::Parser)]
 pub struct FormatAndDiffSubcommand {
+    /// The source path of the code which needs to be formatted
     #[clap(long)]
     old: PathBuf,
+
+    /// The target path of the formatted code
     #[clap(long)]
     new: PathBuf,
 }

crates/moon/src/cli/version.rs

@@ -21,14 +21,14 @@ use std::{env::current_exe, path::Path};
 use anyhow::Context;
 use moonutil::common::{get_moon_version, get_moonc_version, get_moonrun_version};
 
-/// Print version info and exit
+/// Print version information and exit
 #[derive(Debug, clap::Parser)]
 pub struct VersionSubcommand {
-    /// Print all version info
+    /// Print all version information
     #[clap(long)]
     pub all: bool,
 
-    /// Print version info in JSON format
+    /// Print version information in JSON format
     #[clap(long)]
     pub json: bool,
 

crates/moon/tests/test_cases/mod.rs

@@ -428,7 +428,7 @@ fn test_moon_help() {
               generate-build-matrix  Generate build matrix for benchmarking (legacy feature)
               upgrade                Upgrade toolchains
               shell-completion       Generate shell completion for bash/elvish/fish/pwsh/zsh to stdout
-              version                Print version info and exit
+              version                Print version information and exit
               help                   Print this message or the help of the given subcommand(s)
 
             Options:
@@ -441,7 +441,7 @@ fn test_moon_help() {
               -v, --verbose                  Increase verbosity
                   --trace                    Trace the execution of the program
                   --dry-run                  Do not actually run the command
-                  --build-graph              generate build graph
+                  --build-graph              Generate build graph
         "#]],
     );
 }

crates/moonbuild/src/upgrade.rs

@@ -43,7 +43,7 @@ use tokio::fs::set_permissions;
 
 #[derive(Debug, clap::Parser, Clone)]
 pub struct UpgradeSubcommand {
-    /// force upgrade
+    /// Force upgrade
     #[clap(long, short)]
     pub force: bool,
 }

crates/moonutil/src/cli.rs

@@ -43,14 +43,16 @@ pub struct UniversalFlags {
     pub verbose: bool,
 
     /// Trace the execution of the program
+    // The module `n2::trace` doesn't suppose parallelism now, so `--trace`
+    // should be used in conjunction with `--serial` and `--no-parallelize`.
     #[clap(long, global = true)]
     pub trace: bool,
 
     /// Do not actually run the command
     #[clap(long, global = true)]
     pub dry_run: bool,
 
-    /// generate build graph
+    /// Generate build graph
     #[clap(long, global = true, conflicts_with = "dry_run")]
     pub build_graph: bool,
 }

docs/manual-zh/src/tutorial.md

@@ -38,7 +38,7 @@
       generate-build-matrix  Generate build matrix for benchmarking (legacy feature)
       upgrade                Upgrade toolchains
       shell-completion       Generate shell completion for bash/elvish/fish/pwsh/zsh to stdout
-      version                Print version info and exit
+      version                Print version information and exit
       help                   Print this message or the help of the given subcommand(s)
 
     Options:
@@ -51,7 +51,7 @@
       -v, --verbose                  Increase verbosity
           --trace                    Trace the execution of the program
           --dry-run                  Do not actually run the command
-          --build-graph              generate build graph
+          --build-graph              Generate build graph
     ```
 
 2. **Moonbit Language** Visual Studio Code 插件: 可以从 VS Code 市场安装。该插件为 MoonBit 提供了丰富的开发环境，包括语法高亮、代码补全、交互式除错和测试等功能。

docs/manual/src/tutorial.md

@@ -38,7 +38,7 @@ Before you begin with this tutorial, make sure you have installed the following:
       generate-build-matrix  Generate build matrix for benchmarking (legacy feature)
       upgrade                Upgrade toolchains
       shell-completion       Generate shell completion for bash/elvish/fish/pwsh/zsh to stdout
-      version                Print version info and exit
+      version                Print version information and exit
       help                   Print this message or the help of the given subcommand(s)
 
     Options:
@@ -51,7 +51,7 @@ Before you begin with this tutorial, make sure you have installed the following:
       -v, --verbose                  Increase verbosity
           --trace                    Trace the execution of the program
           --dry-run                  Do not actually run the command
-          --build-graph              generate build graph
+          --build-graph              Generate build graph
     ```
 
 2. **MoonBit Language** plugin in Visual Studio Code: You can install it from the VS Code marketplace. This plugin provides a rich development environment for MoonBit, including functionalities like syntax highlighting, code completion, and more.