Fix CLI docs for traces.

crates/aiken/src/cmd/build.rs

@@ -22,17 +22,22 @@ pub struct Args {
     #[clap(short, long)]
     uplc: bool,
 
-    /// Do not remove traces when generating code.
-    #[clap(short, long, value_parser=keep_traces_parser(), default_missing_value="all")]
-    keep_traces: Option<fn(TraceLevel) -> Tracing>,
+    /// Filter traces to be included in the generated program(s).
+    ///   - user-defined: only consider traces that you've explicitly defined (either through the
+    ///   'trace' keyword of via the trace-if-false ('?') operator.
+    ///   - compiler-generated: only included internal traces generated by the Aiken compiler, for
+    ///   example in usage of 'expect'.
+    ///   - all: include both user-defined and compiler-generated traces.
+    /// [optional] [default: all]
+    #[clap(short, long, value_parser=filter_traces_parser(), default_missing_value="all", verbatim_doc_comment)]
+    filter_traces: Option<fn(TraceLevel) -> Tracing>,
 
-    /// Choose the level of tracing
+    /// Choose the verbosity level of traces:
     ///   - silent: disable traces altogether
     ///   - compact: only culprit line numbers are shown on failures
     ///   - verbose: enable full verbose traces as provided by the user or the compiler
-    ///
-    ///
-    #[clap(short, long, value_parser=trace_level_parser(), default_value_t=TraceLevel::Verbose, verbatim_doc_comment)]
+    /// [optional]
+    #[clap(short, long, value_parser=trace_level_parser(), default_value_t=TraceLevel::Silent, verbatim_doc_comment)]
     trace_level: TraceLevel,
 }
 
@@ -42,7 +47,7 @@ pub fn exec(
         deny,
         watch,
         uplc,
-        keep_traces,
+        filter_traces,
         trace_level,
     }: Args,
 ) -> miette::Result<()> {
@@ -50,8 +55,8 @@ pub fn exec(
         watch_project(directory.as_deref(), watch::default_filter, 500, |p| {
             p.build(
                 uplc,
-                match keep_traces {
-                    Some(keep_traces) => keep_traces(trace_level),
+                match filter_traces {
+                    Some(filter_traces) => filter_traces(trace_level),
                     None => Tracing::All(trace_level),
                 },
             )
@@ -60,8 +65,8 @@ pub fn exec(
         with_project(directory.as_deref(), deny, |p| {
             p.build(
                 uplc,
-                match keep_traces {
-                    Some(keep_traces) => keep_traces(trace_level),
+                match filter_traces {
+                    Some(filter_traces) => filter_traces(trace_level),
                     None => Tracing::All(trace_level),
                 },
             )
@@ -72,7 +77,7 @@ pub fn exec(
 }
 
 #[allow(clippy::type_complexity)]
-pub fn keep_traces_parser(
+pub fn filter_traces_parser(
 ) -> MapValueParser<PossibleValuesParser, fn(String) -> fn(TraceLevel) -> Tracing> {
     PossibleValuesParser::new(["user-defined", "compiler-generated", "all"]).map(
         |s: String| match s.as_str() {

crates/aiken/src/cmd/check.rs

@@ -1,4 +1,4 @@
-use super::build::{keep_traces_parser, trace_level_parser};
+use super::build::{filter_traces_parser, trace_level_parser};
 use aiken_lang::ast::{TraceLevel, Tracing};
 use aiken_project::watch::{self, watch_project, with_project};
 use std::{path::PathBuf, process};
@@ -36,11 +36,17 @@ pub struct Args {
     #[clap(short, long)]
     exact_match: bool,
 
-    /// Do not remove traces when generating code
-    #[clap(short, long, value_parser=keep_traces_parser(), default_missing_value="all")]
-    keep_traces: Option<fn(TraceLevel) -> Tracing>,
+    /// Filter traces to be considered during testing:
+    ///   - user-defined: only consider traces that you've explicitly defined (either through the
+    ///   'trace' keyword of via the trace-if-false ('?') operator.
+    ///   - compiler-generated: only included internal traces generated by the Aiken compiler, for
+    ///   example in usage of 'expect'.
+    ///   - all: include both user-defined and compiler-generated traces.
+    /// [optional] [default: all]
+    #[clap(short, long, value_parser=filter_traces_parser(), default_missing_value="all", verbatim_doc_comment)]
+    filter_traces: Option<fn(TraceLevel) -> Tracing>,
 
-    /// Choose the level of tracing
+    /// Choose the verbosity level of traces:
     ///   - silent: disable traces altogether
     ///   - compact: only culprit line numbers are shown on failures
     ///   - verbose: enable full verbose traces as provided by the user or the compiler
@@ -58,7 +64,7 @@ pub fn exec(
         match_tests,
         exact_match,
         watch,
-        keep_traces,
+        filter_traces,
         trace_level,
     }: Args,
 ) -> miette::Result<()> {
@@ -69,8 +75,8 @@ pub fn exec(
                 match_tests.clone(),
                 debug,
                 exact_match,
-                match keep_traces {
-                    Some(keep_traces) => keep_traces(trace_level),
+                match filter_traces {
+                    Some(filter_traces) => filter_traces(trace_level),
                     None => Tracing::All(trace_level),
                 },
             )
@@ -82,8 +88,8 @@ pub fn exec(
                 match_tests.clone(),
                 debug,
                 exact_match,
-                match keep_traces {
-                    Some(keep_traces) => keep_traces(trace_level),
+                match filter_traces {
+                    Some(filter_traces) => filter_traces(trace_level),
                     None => Tracing::All(trace_level),
                 },
             )