Minor rdocs changes

README.rdoc

@@ -1,6 +1,6 @@
 = Rudy - v0.6 ALPHA
 
-Rudy is a command-line development and deployment tool for Amazon Web Services. It helps you build and manage machines in EC2 by organizing them into groups of _environments_ and _roles_. These are called _machine groups_. <tt>stage</tt> is the default environment and <tt>app</tt> is the default role. You can run multiple machines with the same role. These are called _positions_. Rudy also supports running machine groups across availability _zones_. 
+Rudy is a command-line development and deployment tool for Amazon Web Services. It helps you build and manage machines in EC2 by organizing them into groups of _environments_ and _roles_. These are called _machine_ _groups_. <tt>stage</tt> is the default environment and <tt>app</tt> is the default role. You can run multiple machines with the same role. These are called _positions_. Rudy also supports running machine groups across availability _zones_. 
 
 When you put all this together, you have a unique name for every machine. The default machine is:
 

lib/annoy.rb

@@ -102,10 +102,10 @@ def Annoy.numeric_question(factor=:medium)
     [equation, answer]
   end
 
-  # Prints a question to @writer and waits for a response on STDIN. 
-  # It checks whether STDIN is connected a tty so it doesn't block on gets.
+  # Prints a question to +writer+ and waits for a response on STDIN. 
+  # It checks whether STDIN is connected a tty so it doesn't block on gets
   # when there's no human around to annoy. It will return <b>TRUE</b> when
-  # STDIN is NOT connected to a tty.
+  # STDIN is NOT connected to a tty (when STDIN.tty? returns false).
   # * +msg+ The message to print. Default: "Please confirm."
   # Returns true when the answer is correct, otherwise false.
   def Annoy.challenge?(msg="Please confirm.", factor=:medium, flavor=:rand, writer=STDOUT, period=nil)

lib/rudy/utils.rb

@@ -71,9 +71,9 @@ def Rudy.in_situ?
     # * +max+ maximum time to wait (default: 120). Throws an exception when exceeded.
     # * +logger+ IO object to print +dot+ to.
     # * +msg+ the message to print on success
-    # * +bells+ number of terminal bells to ring
-    # Set to nil or false to keep the waiter silent.
-    # The block must return false while waiting. Once it returns true
+    # * +bells+ number of terminal bells to ring. Set to nil or false to keep the waiter silent
+    #
+    # The +check+ block must return false while waiting. Once it returns true
     # the waiter will return true too.
     def waiter(duration=2, max=120, logger=STDOUT, msg=nil, bells=0, &check)
       # TODO: Move to Drydock. [ed-why?]
@@ -274,6 +274,9 @@ def without_indent(str)
 
     ######### Everything below here is TO BE REMOVED. 
 
+    #
+    #
+    # Run a shell command (TO BE REMOVED)
     def sh(command, chdir=false, verbose=false)
       prevdir = Dir.pwd
       Dir.chdir chdir if chdir
@@ -282,7 +285,8 @@ def sh(command, chdir=false, verbose=false)
       Dir.chdir prevdir if chdir
     end
 
-
+    #
+    # Run an SSH command  (TO BE REMOVED)
     def ssh_command(host, keypair, user, command=false, printonly=false, verbose=false)
       #puts "CONNECTING TO #{host}..."
       cmd = "ssh -i #{keypair} #{user}@#{host} "
@@ -297,6 +301,7 @@ def ssh_command(host, keypair, user, command=false, printonly=false, verbose=fal
     end
 
 
+    # (TO BE REMOVED)
     # TODO: This is old and insecure. 
     def scp_command(host, keypair, user, paths, to_path, to_local=false, verbose=false, printonly=false)