HBASE-24803 Unify hbase-shell ::Shell::Commands::Command#help behavior (#2178)

- Update all hbase-shell commands to return help text implicitly
- Add hbase-shell test to ensure all help methods return unindented text
- Set the outermost indentation to zero for the help text of all hbase-shell
  commands by using the squiggly heredoc added in Ruby 2.3.0.
- Document return value of hbck_chore_run and add usage examples to truncate commands
- Update docs to reflect current return value of list command

Signed-off-by: stack <stack@apache.org>

hbase-shell/src/main/ruby/shell/commands/append_peer_namespaces.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class AppendPeerNamespaces < Command
       def help
-        <<-EOF
+        <<~EOF
   Append some namespaces to be replicable for the specified peer.
 
   Set a namespace in the peer config means that all tables in this

hbase-shell/src/main/ruby/shell/commands/clear_compaction_queues.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class ClearCompactionQueues < Command
       def help
-        <<-EOF
+        <<~EOF
           Clear compacting queues on a regionserver.
           The queue_name contains short and long.
           short is shortCompactions's queue,long is longCompactions's queue.

hbase-shell/src/main/ruby/shell/commands/clear_deadservers.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class ClearDeadservers < Command
       def help
-        <<-EOF
+        <<~EOF
           Clear the dead region servers that are never used. Returns an array containing any
           deadservers that could not be cleared.
 

hbase-shell/src/main/ruby/shell/commands/clone_table_schema.rb

@@ -21,7 +21,7 @@ module Shell
     # create a new table by cloning the existent table schema.
     class CloneTableSchema < Command
       def help
-        <<-HELP
+        <<~HELP
           Create a new table by cloning the existent table schema.
           There're no copies of data involved.
           Just copy the table descriptor and split keys.

hbase-shell/src/main/ruby/shell/commands/compact.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class Compact < Command
       def help
-        <<-EOF
+        <<~EOF
           Compact all regions in passed table or pass a region row
           to compact an individual region. You can also compact a single column
           family within a region.

hbase-shell/src/main/ruby/shell/commands/compact_rs.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class CompactRs < Command
       def help
-        <<-EOF
+        <<~EOF
           Compact all regions on passed regionserver.
           Examples:
           Compact all regions on a regionserver:

hbase-shell/src/main/ruby/shell/commands/compaction_state.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class CompactionState < Command
       def help
-        <<-EOF
+        <<~EOF
           Gets compaction status (MAJOR, MAJOR_AND_MINOR, MINOR, NONE) for a table:
           hbase> compaction_state 'ns1:t1'
           hbase> compaction_state 't1'

hbase-shell/src/main/ruby/shell/commands/compaction_switch.rb

@@ -22,7 +22,7 @@ module Shell
     # Switch compaction for a region server
     class CompactionSwitch < Command
       def help
-        <<-EOF
+        <<~EOF
           Turn the compaction on or off on regionservers. Disabling compactions will also interrupt
           any currently ongoing compactions. This state is ephemeral. The setting will be lost on
           restart of the server. Compaction can also be enabled/disabled by modifying configuration

hbase-shell/src/main/ruby/shell/commands/decommission_regionservers.rb

@@ -22,7 +22,7 @@ module Shell
     # Decommission a list of region servers, optionally offload corresponding regions
     class DecommissionRegionservers < Command
       def help
-        <<-EOF
+        <<~EOF
   Mark region server(s) as decommissioned to prevent additional regions from
   getting assigned to them.
 

hbase-shell/src/main/ruby/shell/commands/disable_rpc_throttle.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class DisableRpcThrottle < Command
       def help
-        return <<-EOF
+        <<-EOF
 Disable quota rpc throttle. Returns previous rpc throttle enabled value.
 NOTE: if quota is not enabled, this will not work and always return false.
 

hbase-shell/src/main/ruby/shell/commands/enable_rpc_throttle.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class EnableRpcThrottle < Command
       def help
-        return <<-EOF
+        <<-EOF
 Enable quota rpc throttle. Returns previous rpc throttle enabled value.
 NOTE: if quota is not enabled, this will not work and always return false.
 

hbase-shell/src/main/ruby/shell/commands/get_peer_config.rb

@@ -19,7 +19,7 @@ module Shell
   module Commands
     class GetPeerConfig < Command
       def help
-        <<-EOF
+        <<~EOF
           Outputs the cluster key, replication endpoint class (if present), and any replication configuration parameters
         EOF
       end

hbase-shell/src/main/ruby/shell/commands/hbck_chore_run.rb

@@ -23,7 +23,8 @@ module Shell
         <<-EOF
 Request HBCK chore to run at master side. It will try to find the orphan
 regions on RegionServer or FileSystem and find the inconsistent regions.
-You can check the HBCK report at Master web UI.
+You can check the HBCK report at Master web UI. Returns true if HBCK chore
+ran, or false if HBCK chore is already running.
 
   hbase> hbck_chore_run
 

hbase-shell/src/main/ruby/shell/commands/list_deadservers.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class ListDeadservers < Command
       def help
-        <<-EOF
+        <<~EOF
            List all dead region servers in hbase
            Examples:
            hbase> list_deadservers

hbase-shell/src/main/ruby/shell/commands/list_decommissioned_regionservers.rb

@@ -22,7 +22,7 @@ module Shell
     # List decommissioned region servers
     class ListDecommissionedRegionservers < Command
       def help
-        <<-EOF
+        <<~EOF
   List region servers marked as decommissioned, which can not be assigned regions.
 EOF
       end

hbase-shell/src/main/ruby/shell/commands/list_peer_configs.rb

@@ -19,7 +19,7 @@ module Shell
   module Commands
     class ListPeerConfigs < Command
       def help
-        <<-EOF
+        <<~EOF
           No-argument method that outputs the replication peer configuration for each peer defined on this cluster.
         EOF
       end

hbase-shell/src/main/ruby/shell/commands/list_peers.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class ListPeers < Command
       def help
-        <<-EOF
+        <<~EOF
   List all replication peer clusters.
 
   If replicate_all flag is false, the namespaces and table-cfs in peer config

hbase-shell/src/main/ruby/shell/commands/list_regions.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class ListRegions < Command
       def help
-        return <<EOF
+        <<~EOF
         List all regions for a particular table as an array and also filter them by server name (optional) as prefix
         and maximum locality (optional). By default, it will return all the regions for the table with any locality.
         The command displays server name, region name, start key, end key, size of the region in MB, number of requests
@@ -37,8 +37,7 @@ module Shell
         hbase> list_regions 'table_name', {}, ['SERVER_NAME', 'start_key']
         hbase> list_regions 'table_name', '', ['SERVER_NAME', 'start_key']
 
-EOF
-        nil
+        EOF
       end
 
       def command(table_name, options = nil, cols = nil)

hbase-shell/src/main/ruby/shell/commands/major_compact.rb

@@ -21,7 +21,7 @@ module Shell
   module Commands
     class MajorCompact < Command
       def help
-        <<-EOF
+        <<~EOF
           Run major compaction on passed table or pass a region row
           to major compact an individual region. To compact a single
           column family within a region specify the region name

hbase-shell/src/main/ruby/shell/commands/move_namespaces_rsgroup.rb

@@ -21,7 +21,7 @@ module Shell
     # from one RegionServer group to another.
     class MoveNamespacesRsgroup < Command
       def help
-        <<-CMD
+        <<~CMD
 
   Example:
   hbase> move_namespaces_rsgroup 'dest',['ns1','ns2']

hbase-shell/src/main/ruby/shell/commands/move_servers_namespaces_rsgroup.rb

@@ -21,7 +21,7 @@ module Shell
     # specified namespaces from one group to another.
     class MoveServersNamespacesRsgroup < Command
       def help
-        <<-CMD
+        <<~CMD
 
   Example:
   hbase> move_servers_namespaces_rsgroup 'dest',['server1:port','server2:port'],['ns1','ns2']

hbase-shell/src/main/ruby/shell/commands/recommission_regionserver.rb

@@ -22,7 +22,7 @@ module Shell
     # Recommission a region server, optionally load a list of passed regions
     class RecommissionRegionserver < Command
       def help
-        <<-EOF
+        <<~EOF
   Remove decommission marker from a region server to allow regions assignments.
 
   Optionally, load regions onto the server by passing a list of encoded region names.

hbase-shell/src/main/ruby/shell/commands/remove_peer_namespaces.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class RemovePeerNamespaces < Command
       def help
-        <<-EOF
+        <<~EOF
   Remove some namespaces from the namespaces config for the specified peer.
 
   Examples:

hbase-shell/src/main/ruby/shell/commands/set_peer_exclude_namespaces.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class SetPeerExcludeNamespaces < Command
       def help
-        <<-EOF
+        <<~EOF
   Set the namespaces which not replicated for the specified peer.
 
   Note:

hbase-shell/src/main/ruby/shell/commands/set_peer_exclude_tableCFs.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class SetPeerExcludeTableCFs < Command
       def help
-        <<-EOF
+        <<~EOF
   Set the table-cfs which not replicated for the specified peer.
 
   Note:

hbase-shell/src/main/ruby/shell/commands/set_peer_namespaces.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class SetPeerNamespaces < Command
       def help
-        <<-EOF
+        <<~EOF
   Set the replicable namespaces config for the specified peer.
 
   1. The replicate_all flag need to be false when set the replicable namespaces.

hbase-shell/src/main/ruby/shell/commands/set_peer_replicate_all.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class SetPeerReplicateAll < Command
       def help
-        <<-EOF
+        <<~EOF
   Set the replicate_all flag to true or false for the specified peer.
 
   If replicate_all flag is true, then all user tables (REPLICATION_SCOPE != 0)

hbase-shell/src/main/ruby/shell/commands/set_peer_serial.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class SetPeerSerial < Command
       def help
-        <<-EOF
+        <<~EOF
   Set the serial flag to true or false for the specified peer.
 
   If serial flag is true, then all logs of user tables (REPLICATION_SCOPE != 0) will be

hbase-shell/src/main/ruby/shell/commands/set_peer_tableCFs.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class SetPeerTableCFs < Command
       def help
-        <<-EOF
+        <<~EOF
   Set the replicable table-cf config for the specified peer.
 
   Note:

hbase-shell/src/main/ruby/shell/commands/show_peer_tableCFs.rb

@@ -22,7 +22,7 @@ module Shell
   module Commands
     class ShowPeerTableCFs < Command
       def help
-        <<-EOF
+        <<~EOF
   Show replicable table-cf config for the specified peer.
 
     hbase> show_peer_tableCFs '2'

hbase-shell/src/main/ruby/shell/commands/splitormerge_enabled.rb

@@ -21,12 +21,12 @@ module Shell
     # Command for check split or merge switch status
     class SplitormergeEnabled < Command
       def help
-        print <<-EOF
+        <<-EOF
 Query the switch's state. You can set switch type, 'SPLIT' or 'MERGE'
 Examples:
 
   hbase> splitormerge_enabled 'SPLIT'
-EOF
+        EOF
       end
 
       def command(switch_type)

hbase-shell/src/main/ruby/shell/commands/splitormerge_switch.rb

@@ -22,13 +22,13 @@ module Shell
     # Command for set switch for split and merge
     class SplitormergeSwitch < Command
       def help
-        print <<-EOF
+        <<-EOF
 Enable/Disable one switch. You can set switch type 'SPLIT' or 'MERGE'. Returns previous split state.
 Examples:
 
   hbase> splitormerge_switch 'SPLIT', true
   hbase> splitormerge_switch 'SPLIT', false
-EOF
+        EOF
       end
 
       def command(switch_type, enabled)

hbase-shell/src/main/ruby/shell/commands/truncate.rb

@@ -21,8 +21,11 @@ module Shell
   module Commands
     class Truncate < Command
       def help
-        <<-EOF
+        <<~EOF
   Disables, drops and recreates the specified table.
+
+  Example:
+    hbase> truncate 'my_table'
 EOF
       end
 

hbase-shell/src/main/ruby/shell/commands/truncate_preserve.rb

@@ -21,8 +21,11 @@ module Shell
   module Commands
     class TruncatePreserve < Command
       def help
-        <<-EOF
-  Disables, drops and recreates the specified table while still maintaing the previous region boundaries.
+        <<~EOF
+  Disables, drops and recreates the specified table while still maintaining the previous region boundaries.
+
+  Example:
+    hbase> truncate_preserve 'my_table'
 EOF
       end
 

hbase-shell/src/test/ruby/shell/commands_test.rb

@@ -25,9 +25,26 @@ require 'shell'
 # Tests whether all registered commands have a help and command method
 
 class ShellCommandsTest < Test::Unit::TestCase
+
+  ##
+  # Determine the indentation of the given text
+  #
+  # @param [String] text
+  # @return [Integer] number of whitespace characters used for indentation
+  def determine_indentation(text)
+    # Ignore lines only containing whitespace. For all other lines, capture
+    # the number of whitespace characters preceding the first non-whitespace
+    # character. Return the minimum number found.
+    text.scan(/^([ \t]*)[^\s].*$/).flatten.map { |space| space.length }.min
+  end
+
   Shell.commands.each do |name, klass|
-    define_test "#{name} command class #{klass} should respond to help" do
-      assert_respond_to(klass.new(nil), :help)
+    define_test "#{name} command class #{klass} should return help" do
+      result = klass.new(nil).help
+      # check that help text exists and is non-empty
+      assert(result.is_a?(String) && result.length > 0)
+      # check that the help text is not indented
+      assert(determine_indentation(result) == 0)
     end
 
     define_test "#{name} command class #{klass} should respond to :command" do

src/main/asciidoc/_chapters/shell.adoc

@@ -324,7 +324,7 @@ TABLE
 t
 1 row(s) in 0.1040 seconds
 
-=> #<#<Class:0x7677ce29>:0x21d377a4>
+=> ["t"]
 hbase(main):017:0> tables.map { |t| disable t ; drop  t}
 0 row(s) in 2.2510 seconds