Incorrect docstring for parse-opts

Question

In the docstring for clojure.tools.cli/parse-opts (seen here), it says,

:id           The key for this option in the resulting option map. This
              is normally set to the keywordized name of the long option
              without the leading dashes.

              Multiple option entries can share the same :id in order to
              transform a value in different ways, but only one of these
              option entries may contain a :default(-fn) entry.

              This option is mandatory.

The final line says "This option is mandatory." which is technically true for parse-opts' internals, but it's not true for users because (as the first paragraph says) :id is also generated by keywordizing the long option.

May I recommend changing it to be more explicit? Something like "If a long option is not provided, this option is mandatory."

Answer 1

This relates to https://ask.clojure.org/index.php/14260/providing-nil-for-long-option-tools-cli-does-seem-work-readme and I plan to update the docstrings and readme to fix both.

Comments

Thanks Sean, I'll mark this as answered once you've handled it.

---

The docstring and the readme have been updated. A new release will get cut at some point, but that's almost the only change since the last release so it might be a while.