Better built-in documentation for console commands

BrainPortal/config/console_rc/lib/bourreau_console.rb

@@ -49,5 +49,10 @@ def self.console(id) #:nodoc:
 ========================================================
 Feature: invoking a console on a bourreau, for debugging
 ========================================================
-  Activate with: bourreau.console ; Bourreau.console(id)
+  bourreau.console     # if bourreau is a Bourreau object
+  Bourreau.console(id) # if you have th ID
+
+  Note: do not connect from the same terminal that started
+  the bourreau with 'ibc', the pseudo-ttys get confused.
+  Start another rails console in another terminal if needed.
 FEATURES

BrainPortal/config/console_rc/lib/current_user_project.rb

@@ -39,17 +39,20 @@ def current_project #:nodoc:
 #   cu id
 #   cu /regex/
 def cu(user=:show)
-  return $_current_user if user == :show
+  if user == :show
+    puts "Current user is: #{$_current_user.try(:login) || "(nil)"}"
+    return $_current_user
+  end
   if user.nil? || user.is_a?(User)
     $_current_user = user
   elsif user.is_a?(Numeric) || (user.is_a?(String) && user =~ /\A\d+\z/)
     $_current_user = User.find(user)
-  elsif user.is_a?(String)
+  elsif user.is_a?(String) || user.is_a?(Symbol)
     $_current_user = User.where([ "(login like ?) OR (full_name like ?)", "%#{user}%", "%#{user}%" ]).first
   elsif user.is_a?(Regexp)
     $_current_user = User.all.detect { |u| (u.login =~ user) || (u.full_name =~ user) }
   else
-    raise "Need a ID, User object, regex, or a string."
+    raise "Need an ID, User object, regex, symbol or a string that represents a user."
   end
   puts "Current user is now: #{$_current_user.try(:login) || "(nil)"}"
 end
@@ -60,8 +63,12 @@ def cu(user=:show)
 #   cp 'name'
 #   cp id
 #   cp /regex/
+#   cp nil
 def cp(group='show me')
-  return $_current_project if group == 'show me'
+  if group == 'show me' # the fake default value
+    puts "The current project is: #{$_current_project.try(:name) || "(unset, meaning ALL projects)"}"
+    return $_current_project
+  end
   if group.nil? || group.is_a?(Group)
     $_current_project = group
   elsif group.is_a?(Numeric) || (group.is_a?(String) && group =~ /\A\d+\z/)
@@ -71,7 +78,7 @@ def cp(group='show me')
   elsif group.is_a?(String)
     $_current_project = Group.where([ "name like ?", "%#{group}%" ]).first
   else
-    raise "Need a ID, Group object, regex or a string."
+    raise "Need a ID, Group object, regex, symbol or a string that represents a group."
   end
   puts "Current project is now: #{$_current_project.try(:name) || "(nil)"}"
 end

BrainPortal/config/console_rc/lib/fast_finder.rb

@@ -183,6 +183,13 @@ def to_summary
 ========================================================
 Feature: fast finder for anything
 ========================================================
-  Activate with: fff 'string' ; fff id
+  fff 'string'
+  fff id
+
+  Will search files, users, projects etc and assign
+  instance variables in the console with everything it
+  finds. Single letter (e.g. @u) if a single result is
+  found, double letters (e.g. @uu) if multiple results
+  are found.
 FEATURES
 

BrainPortal/config/console_rc/lib/interactive_bourreau_control.rb

@@ -493,6 +493,11 @@ def bash_command_on_one_bourreau(b,comm,&block) #:nodoc:
 ========================================================
 Feature: Interactive Bourreau Control
 ========================================================
-  Activate with: ibc
+  ibc          # interactive CLI
+  ibc "o p q"  # non-interactive
+
+  This is an interactive tool with a built-in help,
+  allowing the admin to start and stop bourreaux,
+  and query their status etc. Useful during maintenance.
 FEATURES
 

BrainPortal/config/console_rc/lib/logger_rc.rb

@@ -61,9 +61,12 @@ def set_log_level(level) #:nodoc:
 ========================================================
 Feature: Toggling ActiveRecord logging messages
 ========================================================
-  (These things: "User Load (0.8ms) SELECT `users`...")
-  Turn on or off permanently with: do_log ; no_log
-  Note: these two methods can take a block and apply the
-  log setting restriction while running it.
+  no_log  # turn off SQL logging
+  do_log  # turn on SQL logging
+
+  These are the SQL message shown whenever the rails command
+  triggers a database access, e.g. "User Load (0.8ms) SELECT..."
+  Note: these two methods can take also take a Ruby block:
+  no_log { User.count }  # no logging just during the block
 FEATURES
 

BrainPortal/config/console_rc/lib/pretty_view.rb

@@ -431,6 +431,10 @@ def pretview
 ========================================================
 Feature: Pretty View for some objects
 ========================================================
-  Activate with: pv obj [, obj , ...]
+  pv obj [, obj , ...]
+
+  If an object responds to 'pretview', show that view.
+  Currently implemented: User, CbrainTask, Group, and
+  about a dozen other common CBRAIN models.
 FEATURES
 

BrainPortal/config/console_rc/lib/print_log.rb

@@ -40,6 +40,8 @@ def plog(*args)
 ========================================================
 Feature: print ActiveRecordLog of some objects
 ========================================================
-  Activate with: plog obj [, obj , ...]
+  plog obj [, obj , ...]
+
+  If an object has an internal log, shows that log.
 FEATURES
 

BrainPortal/config/console_rc/lib/reports.rb

@@ -109,9 +109,8 @@ def last(lim=20, user=nil)
 ========================================================
 Feature: Reports
 ========================================================
-  In the console simply type:
-    trans    : report of active transfers between resources and DP
-    acttasks : active tasks
-    last [n] : last connected users (n = limit, default 20)
+  trans    : report of active transfers between resources and DP
+  acttasks : report active tasks
+  last [n] : last connected users (n = limit, default 20)
 FEATURES
 

BrainPortal/config/console_rc/lib/shortcuts.rb

@@ -32,8 +32,8 @@
 ========================================================
 Feature: shortcuts to view helpers
 ========================================================
-  Invoke these directly: h("jack&jill"), model_path(),
+  Invoke these directly: h("jack&jill"), user_path(1),
   pretty_size(1234567), etc.
-  Other view helpers: helper.helper_method(args)
+  Other view helpers can also be tested with: helper.helper_method(args)
 FEATURES
 

BrainPortal/config/console_rc/lib/wirble_hirb_looksee.rb

@@ -121,8 +121,8 @@ def sql(command)
 ========================================================
 Feature: Hirb pretty model tables, and table helpers
 ========================================================
-  Models have pretty unicode tables: User.limit(4)
-  Full attributes in tables with: 'tv obj'
+  Many models have pretty unicode tables: 'User.limit(4)'
+  See all attributes as a table with: 'tv obj'
   Console commands: 'table', 'htable' and 'view'
   Toggle with: Hirb.enable ; Hirb.disable
   (See the doc for the gem Hirb for more info)