Sub commands should show separate help messages when used incorrectly

[ericmarkmartin]

Currently, spotify vol will give you a message if you use the command incorrectly:

$ spotify vol foo
Improper use of 'vol' command
The 'vol' command should be used as follows:
  vol up                       # Increases the volume by 10%.
  vol down                     # Decreases the volume by 10%.
  vol [amount]                 # Sets the volume to an amount between 0 and 100.
  vol                          # Shows the current Spotify volume.

I think it would be wise to make all commands conform to this, because otherwise things like this happen:

$ spotify toggle
$
$ spotify toggle foo
$

I suppose that for most commands, this isn't particularly helpful (status, next, etc) but for some current commands and especially in the future, I think it would be helpful as new commands are implemented.

Additionally, I think that sub commands should allow this help menu to be invoked with "help" parameter, eg:

$ spotify vol help
The 'vol' command should be used as follows:
  vol up                       # Increases the volume by 10%.
  vol down                     # Decreases the volume by 10%.
  vol [amount]                 # Sets the volume to an amount between 0 and 100.
  vol                          # Shows the current Spotify volume.

Maybe that "should" should be changed to "can", but at that point I'm just messing with semantics.

Of course, if we decide to go this route, spotify play poses an issue:

$ spotify play help
Searching tracks for: help
Playing (help Search) -> Spotify URI: spotify:track:55jAHaYaZtUImilMnroSna
EricMacbookPro:shpotify ericmarkmartin$ spotify status
Spotify is currently playing.
Artist: The Beatles
Album: Live At The Hollywood Bowl
Track: Help! - Live / Remastered
Position: 0:02 / 2:52

which totally skipped my mind. Unfortunately, this is a completely valid usage, so we'll have to think of a way to deal with that...

Of course, we could also implement a synonymous -h flag for sub commands.

Side note, and maybe I'm getting too ambitious (especially for 1.3.0) but just screwing around with the implementation of this sort of a feature is indicating to me that maybe it's time for the sub commands to separated out into their own files? I don't know.

Thoughts?

[tpritc]

I like the idea of help commands, as it really helps to expose functionality in a user interface that has little affordance to help the user.

For your spotify play help issue, perhaps we could use spotify help play, meaning we could work for an arbitrary number of instances, and we could even seek forward a few commands to give more in-depth help. Not sure how standard either of these options are, and on the command line, it's almost always better to conform to standards, even if it makes our lives designing the interface a little harder.

[ericmarkmartin]

@tpritc, I just did some digging and I think you're right about spotify help [cmd] vs spotify [cmd] help. For instance git and brew use git help [cmd] and brew help [cmd] respectively.

With that decided, we could relatively easily add to the help command to implement this functionality, but I'm wondering if, in the pursuit of modularity and saving our future selves time as opposed to our current selves, we shouldn't start splitting sub-commands up into their own files.

Of course, for anything so major we'll need @hnarayanan to take a look, but some preliminary discussion wouldn't hurt.

[hnarayanan]

I will take a look in a bit. I am trying to focus on some other projects right now, and they're requiring a lot of my concentration. :)

[ericmarkmartin]

@hnarayanan thanks for checking in. Don't worry about it: I'm sure you have plenty of other important things to focus on at any given moment and I'm not in a rush on any of these issues.

[hnarayanan]

I know it's been like a 100 years, but if anyone is willing to look at this, I am happy to talk about it.

[ericmarkmartin]

Hey, it’s been a while. I’m actually on spring break now and would be down to tackle this