Clarify boolean switch alias helpers

Author: t-kalinowski

R/args.R

@@ -19,10 +19,10 @@ process_args <- function(args, app) {
     for (i in seq_along(app_opts)) {
       if (identical(short, app_opts[[i]][["short"]])) {
         if (identical(app_opts[[i]][["arg_type"]], "switch")) {
-          if (show_positive_alias(app_opts[[i]])) {
+          if (shows_positive_alias(app_opts[[i]])) {
             return(paste0("--", names(app_opts)[[i]]))
           }
-          if (show_negative_alias(app_opts[[i]])) {
+          if (shows_negative_alias(app_opts[[i]])) {
             return(paste0("--no-", names(app_opts)[[i]]))
           }
           return(paste0("--", names(app_opts)[[i]]))
@@ -99,7 +99,7 @@ process_args <- function(args, app) {
       if (
         !is.null(spec) &&
           identical(spec$arg_type, "switch") &&
-          !has_positive_alias(spec)
+          !accepts_positive_alias(spec)
       ) {
         stop_unrecognized_arg(a)
       }
@@ -125,7 +125,7 @@ process_args <- function(args, app) {
       if (
         !is.null(spec) &&
           identical(spec$arg_type, "switch") &&
-          !has_positive_alias(spec)
+          !accepts_positive_alias(spec)
       ) {
         stop_unrecognized_arg(a)
       }
@@ -141,7 +141,7 @@ process_args <- function(args, app) {
           !is.null(alt_spec) &&
             identical(alt_spec$arg_type, "switch")
         ) {
-          if (has_negative_alias(alt_spec)) {
+          if (accepts_negative_alias(alt_spec)) {
             spec <- alt_spec
             val <- "false"
             name <- alt_name

R/help.R

@@ -194,8 +194,8 @@ print_app_help <- function(app, yaml = TRUE, command_path = character()) {
       default_value <- format_default_value(opt$default)
       positive_flag <- paste0("--", cli_name)
       negative_flag <- paste0("--no-", cli_name)
-      show_positive <- show_positive_alias(opt)
-      show_negative <- show_negative_alias(opt)
+      show_positive <- shows_positive_alias(opt)
+      show_negative <- shows_negative_alias(opt)
       if (!show_positive && !show_negative) {
         flag <- paste(positive_flag, format_placeholder(name))
         if (!is.null(short_flag) && nzchar(short_flag)) {

R/utils.R

@@ -79,7 +79,9 @@ check_bool_switch_default <- function(default) {
   }
 }
 
-has_positive_alias <- function(opt) {
+# Parsing is intentionally more permissive than help. accepts_* controls
+# command-line forms; shows_* controls the concise help surface.
+accepts_positive_alias <- function(opt) {
   stopifnot(identical(opt[["arg_type"]], "switch"))
 
   default <- opt[["default"]]
@@ -88,7 +90,7 @@ has_positive_alias <- function(opt) {
   TRUE
 }
 
-has_negative_alias <- function(opt) {
+accepts_negative_alias <- function(opt) {
   stopifnot(identical(opt[["arg_type"]], "switch"))
 
   default <- opt[["default"]]
@@ -101,7 +103,7 @@ has_negative_alias <- function(opt) {
   TRUE
 }
 
-show_positive_alias <- function(opt) {
+shows_positive_alias <- function(opt) {
   stopifnot(identical(opt[["arg_type"]], "switch"))
 
   default <- opt[["default"]]
@@ -110,13 +112,13 @@ show_positive_alias <- function(opt) {
   isFALSE(default) || isTRUE(is.na(default))
 }
 
-show_negative_alias <- function(opt) {
+shows_negative_alias <- function(opt) {
   stopifnot(identical(opt[["arg_type"]], "switch"))
 
   default <- opt[["default"]]
   check_bool_switch_default(default)
 
-  has_negative_alias(opt) && (isTRUE(default) || isTRUE(is.na(default)))
+  accepts_negative_alias(opt) && (isTRUE(default) || isTRUE(is.na(default)))
 }
 
 `append<-` <- function(x, after = NULL, value) {

docs/boolean-options.md

@@ -4,6 +4,10 @@ Logical defaults become boolean command-line inputs. Help output shows the
 most useful spelling for changing the default, while parsing also accepts
 explicit boolean values for convenience.
 
+Help output is intentionally narrower than parsing. For example, `foo <- TRUE`
+normally shows `--no-foo`, but `--foo=false` is still accepted because it is an
+explicit boolean value for `foo`.
+
 In the table below, `TRUE`, `FALSE`, and `NA` are the resulting R values.
 `reject` means the command-line form is not accepted.
 
@@ -23,4 +27,5 @@ value after `--foo`.
 
 `#| negative_alias: false` only disables the generated `--no-foo` spelling.
 It does not disable the positive spelling or explicit value forms such as
-`--foo=false`.
+`--foo=false`. With `foo <- TRUE`, that leaves no default-changing bare alias,
+so help shows `--foo <FOO>` as an explicit-value form.