Ability to provide help information for bot and commands WIP

[accessd]

Hi @dblock!
In process now. I'd like to add ability for showing all possible commands. What do you think about it?

[dblock]

It's a great idea, but maybe part of help? For example each command could self-document?

[accessd]

Yep, I thought about help. So, for example help shows all possible commands and then you able to ask about concrete command in format help <command>.
Command could be self-documented as far as it's possible. But what about if user have ability to add some description to his own command?

[dblock]

Right, the author of the command could document it, maybe something like this?

module SlackRubyBot
  module Commands
    class Hi < Base
      name 'hi'
      desc 'Says hello.'
      long_desc 'When a user types "hi" the bot will reply "hello". This helps everyone stay polite.'
    end
  end
end

[accessd]

Ok, so it's optional feature and we show only documented commands?

[accessd]

I mean in list of possible commands. We can show not documented plain commands too.

[dblock]

I say we show all and make it mandatory feature part of the help command. You can remove the help command or roll your own (we should document how) if you don't want this behavior.

[accessd]

So, we'll put the logic that checks that all the commands have documented in SlackRubyBot::Commands::Help and throw an exception if are not. Right?

You can remove the help command or roll your own

Do you mean for specific command?

[dblock]

You can default to blank when a command isn't documented.

I mean if you want to replace the built-in Help command (that you're coding) by something else you can always make your own.

[accessd]

I think that name of the command shouldn't be blank. Others can be blank.

What about backward compatibility? User should be define all help attributes or replace built-in help command?

[dblock]

I wouldn't worry too much about backward compatibility here. We can provide an entry in UPGRADING that explains how to do it by hand.

[accessd]

Updated 😃
So, now you can set description for bot and commands.

How it looks:

class MarketBot < SlackRubyBot::Bot
  title 'MarketBot'
  desc 'Shows the last finance quotes'
  long_desc 'Understands commands like: How\'s AMZN today?'

[dblock]

I assume we don't require this? For demo purposes maybe remove this line?

[dblock]

Overall, this is great, but I still have a problem with scope. When something inherits from Commands::Base and declares 1 command it works great, but most people these days define multiple command 'foo', so we would want to allow something like this:

title 'foo'
command 'foo' do ...
end

title 'bar'
command 'bar' do ...
end

Which just means that a new title needs to reset a stack of options and add itself to an array of things and not set self.title = .... But then we're going down a rabbit hole which we already had to undo in other projects like https://github.com/ruby-grape/grape#parameters, so we should learn from that and maybe write help descriptions like so:

help do
  title 'Weather Bot'
  desc 'This bot tells you the weather.'

  command 'clouds' do
    desc 'Tells you how many clouds there're above you.'
  end

  command 'What's the weather in <city>?' do
    desc 'Tells you the weather in a <city>.'
    long_desc '...'
  end
end

What do you think?

[accessd]

Yeah, I see. I think it would be great. I'll try to implement it.

[accessd]

But may be long_desc is excess. Because I don't when show it in case command 'What's the weather in <city>?' do, for example.

[accessd]

updated.
how it looks now:

[dblock]

You can't have private class methods. You can just make this a regular method.

[accessd]

Really, it's possible. http://domon.cc/2013/12/25/private-class-methods-in-ruby/
I already have done it here: https://github.com/dblock/slack-ruby-bot/blob/master/lib/slack-ruby-bot/commands/base.rb#L81 😃

[dblock]

I'm learning. Thanks!

[dblock]

This is great. It needs specs, documentation, CHANGELOG, etc and it will be good to go.

[accessd]

ready. check it, please.

[dblock]

This is great, merged.

[dblock]

@accessd Would appreciate a second look at #96 that now references the actual class instead of class name for picking help commands, plus some inheritance fixes.

[accessd]

@dblock #96 looks great!