Add more information for beginners

Andre601 commented 4 years ago

I like the system of the .commodore file, but with it comes additional stuff which may seem hard to understand, especially if you're a beginner at understanding tab-completion and command suggestions.

What is quotable_phrase for? What does single_word change? Are colours changeable, or set? Those are only a few of the many questions I had to ask about the file system itself. I can't imagine how it must feel like for people who want to use the code-version instead.

So having a separate wiki, where you list the various options and their respective usage would be a good way to give information to beginners who stumble upon this and wonder how to use it.

Andre601 commented 4 years ago

An additional thing I also realized is, that there isn't a clear way of distinguishing, how to set optional and required params.

For example, when I would make a command which allows me to sell items for a certain price and make the number of items sold optional (defaulting to 1) then how would I setup commodore for the following command variations?

/sell STONE 10 (Selling one stone for 10)
/sell STONE 10 16 (Selling 16 stone for 10)

Andre601 commented 3 years ago

This is still something I think should be applied. If at all should it at least have a wiki.

The issues I mentioned in my previous posts still apply now.

There is no list or similar showing all available brigardier:<type> options such as brigardier:integer and brigardier:string
There is no explanation about possible extra options. Apparently is there a single_word and greedy_phrase option. What are the differences? When you you use them? Any extra options?
A .commodore file example is given but no attempt is made in explaining the overall syntax. Sure, the /day example may give some idea on how the syntax works, but it doesn't mention specific patterns for certain arguments. How f.e. does syntax look for the /tp command using coordinates? How do you allow to also have players as targets?
Commodore#register has a Predicate<Player> option that could be used to determine when to show arguments. But how to set it up, so that it works with command args (i.e. /time set day requires time.set.day permission. How to set that it won't show day for /time set when lacking the permission?)

It's sad to see this being a good library, yet lack so much info on how to use it and to make it more beginner-friendly. And considering this issue didn't receive an answer for more than a year is it really sad.

lucko commented 3 years ago

I've enabled the wiki tab on this repo and granted edit access to anyone.

I don't have time to personally write any more documentation at the moment, but if you or someone else would like to then be my guest :)

lucko commented 3 years ago

I've just seen that you have started to - that's great! Thank you :)

Andre601 commented 3 years ago

I've just seen that you have started to - that's great! Thank you :)

Yes. I already created some stuff and hopefully, the info is correct. If something is different than described, or if the description should be improved, lmk.

lucko / commodore

Add more information for beginners #9