Unclear/undocumented value interface.

[mibli]

So I've found myself quite struggling to figure out how to use the returned code. Perhaps documentation or example with the use cases of the functions should be added:

Use case that didn't work:

constexpr char USAGE[] = R"(i3 geometric window switcher

Usage:
  i3switch (next | prev) [wrap]
  i3switch number <num>
  i3switch (left | up | right | down) [wrap]
  i3switch (-h | --help)
)"

int main(int argc, char *argv) {
  auto args = docopt::docopt(std::string(USAGE), std::vector<std::string>(argv + 1, argv + argc), true, "0.1.0");
  
  int order;
  if (args["number"]) {
    order = args["<num>"].asLong();
  }
  
  direction2d = Direction2d::INVALID;
  for (std::pair<std::string, Direction2d> pair : direction_2d_map) {
    if (args[pair.first]) {
      direction2d = pair.second;
      break;
    }
  }
}

Command: i3 switch right

By instinct I was looking for a common pattern like args["left"] or args["left"].empty() to check if argument was present. I expected that direction2d would be set to first encountered direction, and order to contain the value if number keyword was present.

Turns out it's unclear what empty does, because You have to use asBool. And You can't figure it out unless You dig into the parsing, which shouldn't happend for API... So perhaps in example or in README these should get covered?

[jaredgrubb]

I'm always open to having some documentation PR's to help improve these and make it clearer! Thanks for the idea!

[mibli]

I'm thinking, maybe if options are never empty, maybe using bool(value) on options could throw? This is one way of letting developer know it's not the interface he's looking for.

[jaredgrubb]

Are you proposing that the current behavior should be tweaked? Or that the documentation should be clarified to match the behavior?

[mibli]

I'm thinking both :)