Adding a single subcommand makes it mandatory?

[polarathene]

This is not communicated clearly in documentation, and I've tried searching discussions and issues for clarification but unsuccessful.

Using the derive API, I had a simple program with an arg and switch:

use bpaf::Bpaf;

#[derive(Bpaf)]
#[bpaf(options, version)]
struct Args {
  /// Port to bind
  #[bpaf(short, long, argument("PORT"), fallback(80), display_fallback)]
  port: u16,

  /// Capability awareness enables the effective capability when permitted
  aware: bool,
}

When I added a subcommand with:

struct Args {
  //...

  #[bpaf(external)]
  inspect: Inspect,
}

#[derive(Bpaf, Debug)]
#[bpaf(command("inspect"))]
/// Show the capabilities available to the process
struct Inspect {
  #[bpaf(external(set), collect, group_help("Capability sets to display"))]
  sets: std::collections::HashSet<Set>,
}

I found I could not run my program without the subcommand now, and the help text indicated it was mandatory. So I tried to make it optional like the docs suggest with Option<Inspect>, but that doesn't seem compatible with commands:

error[E0308]: mismatched types
  --> src/main.rs:19:3
   |
19 |   inspect: Option<Inspect>,
   |   ^^^^^^^ expected `Option<Inspect>`, found `Inspect`
   |
   = note: expected enum `Option<Inspect>`
            found struct `Inspect`
help: try wrapping the expression in `Some`
   |
19 |   inspect: Some(inspect): Option<Inspect>,
   |   ++++++++++++++       +

Attempted to convert that to an enum if that would have made it happy:

struct Args {
  //...

  #[bpaf(external)]
  inspect: Option<Inspect>,
}

#[derive(Bpaf, Debug)]
// Doc comment moved with command,
// otherwise a doc comment here functions like `group_help`
// replacing the default "Available commands:" section heading
enum Inspect {
  /// Show the capabilities available to the process
  #[bpaf(command("inspect"))]
  Sets(
    #[bpaf(external(set), collect, group_help("Capability sets to display"))]
    std::collections::HashSet<Set>
  ),
}

but no luck:

error[E0308]: mismatched types
  --> src/main.rs:19:3
   |
19 |   inspect: Option<Inspect>,
   |   ^^^^^^^ expected `Option<Inspect>`, found `Inspect`
   |
   = note: expected enum `Option<Inspect>`
              found enum `Inspect`
help: try wrapping the expression in `Some`
   |
19 |   inspect: Some(inspect): Option<Inspect>,
   |   ++++++++++++++       +

The suggestion isn't valid so ignore that.

[polarathene]

Solved: The optional annotation docs don't touch on it, perhaps it's assumed you've already read the top of this docs page for derive-specific considerations?

That section does demonstrate optional as a valid annotation for derive API, and that it is necessary in some contexts:

// Option wrapping the type is not sufficient here
// you also need to add the `optional` annotation,
// probably because it's annotated with `external`?
#[bpaf(external, optional)]
inspect: Option<Inspect>,

Now it's optional 🥳

Usage: capability-aware [-p=PORT] [--aware] [COMMAND ...]

[pacak]

Indeed. external just substitutes parser creation for a function call to make the parser. Since it doesn't know what type the function will produce - it disables automatic detection for Option/Vec wrappers (many and optional) and you have to add them yourself. Initially when making documentation I assumed people would first go over the intro section but it seems it's not happening :) I have a bigger doc refactor in progress, will make sure to cover this in greater details.

[polarathene]

Initially when making documentation I assumed people would first go over the intro section but it seems it's not happening :)

Yeah, I write doc for a project as well and it's not uncommon the larger the docs get for users that just want to get going 😅

I started at the earlier pages, but after I had the basics working it was more about "can I do what I want, and if so how?", at which point I was jumping through the pages to different methods and looking at derive examples.

---

I really like the co-location for the combinatoric and derive APIs with common output section and examples afterwards, those are excellent!

Only issue I had with the docs was navigating felt very messy/scattered and I got lost often. I would primarily be interested in the derive examples and what annotations / API I had available to work with. I'd use the sidebar on the left often as that provided better visibility of similar options/features I could explore.

Took a while to make sense of switch => flag => req_flag, where the latter was what I was interested in but for derive API was less obvious in usage. I basically wanted a switch that when true produced an enum variant, while the flag example required an alternative enum variant for false condition, but you could not use an Option with Some() for true and None for false.

I then discovered that it was possible to get a better DX with many (and later collect for uniqueness via a HashSet), which worked well as that enum had multiple variants, each to be treated like unique switch and I was interested in only the true values mapped to the variants, which I would later iterate over in my program. Might be a good example for your docs? 😝

---

I have a bigger doc refactor in progress, will make sure to cover this in greater details.

🥳

Appreciated!

There are nice doc generators like MkDocs which are easy to manage (I've got that setup with Github Actions to deploy to GH Pages) if that would help keep focus on the API (there's a content tabs feature which would suit switching between combinatoric and derive APIs along with the output/examples). It's just markdown with some extra features.

The crates docs approach is interesting, but had quite a bit of noise? Perhaps your refactor will minimize that:

Here it looks a bit awkward with all the different navigation zones and noise in naming conventions (which seem a bit specific the docs generator, like the explicit numbers for ensuring order of links?)

Whereas here, we have some repeated information with the "modules" that is named differently, and on the left-sidebar several different doc links, and at this point perhaps only the "Functions" are going to be of most interest, yet other related features belong on other pages. Bit of a battle with the actual crate docs vs more extensive documentation for users I guess 😅