From fdeeabc892be812cf02218d5da758b383ef06298 Mon Sep 17 00:00:00 2001
From: Giacomo Cavalieri <giacomo.cavalieri@icloud.com>
Date: Thu, 2 Oct 2025 19:01:21 +0200
Subject: [PATCH] improve help text for run, test, and dev commands

---
 CHANGELOG.md            | 7 +++++++
 compiler-cli/src/lib.rs | 6 ++++++
 2 files changed, 13 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cd4b7d52fa7..952b9e54574 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Build tool
+
+- The help text displayed by `gleam dev --help`, `gleam test --help`, and
+  `gleam run --help` has been improved: now each one states which function it's
+  going to run.
+  ([Giacomo Cavalieri](https://github.com/giacomocavalieri))
+
 ### Bug fixes
 
 - Fixed a bug where the "Extract function" code action would not properly
diff --git a/compiler-cli/src/lib.rs b/compiler-cli/src/lib.rs
index 106055551be..fc6fa433493 100644
--- a/compiler-cli/src/lib.rs
+++ b/compiler-cli/src/lib.rs
@@ -215,6 +215,8 @@ enum Command {
     Shell,
 
     /// Run the project
+    ///
+    /// This command runs the `main` function defined in `src/<PROJECT_NAME>.gleam`
     #[command(trailing_var_arg = true)]
     Run {
         #[arg(short, long, ignore_case = true, help = target_doc())]
@@ -235,6 +237,8 @@ enum Command {
     },
 
     /// Run the project tests
+    ///
+    /// This command runs the `main` function defined in `test/<PROJECT_NAME>_test.gleam`.
     #[command(trailing_var_arg = true)]
     Test {
         #[arg(short, long, ignore_case = true, help = target_doc())]
@@ -247,6 +251,8 @@ enum Command {
     },
 
     /// Run the project development entrypoint
+    ///
+    /// This command runs the `main` function defined in `dev/<PROJECT_NAME>_dev.gleam`
     #[command(trailing_var_arg = true)]
     Dev {
         #[arg(short, long, ignore_case = true, help = target_doc())]