Please improve the docs

[banister]

I like this project but the docs are very disorganized and hard to understand.

I just want the docs to be organized with headings so it's easy to know:

• How to create a boolean flag option
• How to create an option that takes a value (and/or set a default)

Just finding the answers to those simple questions is very difficult with the current doc organization. I'm not the only one, multiple people i talked to had the same issue.

Please improve this! Cos this is otherwise a great project! :)

[banister]

I see now that you use cmdl[{"-h", "--help"}] for a boolean option but cmd({"-t", "--time"}) for an option that takes a param. I personally find this confusing and not discoverable - the syntaxes also look very similar and easy to over-look.

Why not just do something like this instead:

cmd.flag({"-h", "--help"}) and cmd.param({"-t", "--time"}) this is instantly much more intuitive, and discoverable - IMO anyway!

[adishavit]

Thank you for your feedback 🙏
It makes me happy to know you and your colleagues are finding Argh! useful.

Re: your first comment:
I actually made great efforts to make the docs accessible and complete.
I'm glad you pointed out that it is still lacking.
Could I trouble you to make a PR to add the missing section to the docs? Maybe a Q&A or Cookbook Section?

As for your second request, it kinda breaks the lib's minimalist syntax and approach but I am not immediately against. It has never come up. Let me think about it.
If you make a (separate) PR for this too, we could consider and discuss it in the PR thread.