Document updates for 0.4.0 release (#8)

Update the doc comments and restructure the class includes to stay
compliant with yardoc and keep our generated documentation clean.

README.md

@@ -55,7 +55,7 @@ result.exit_code
 result = connection.run("ls /root", sudo: true)
 
 # Run a command on the remote host with elevated shell privilege
-result = connection.run("ipconfg", shell: :elevated)
+result = connection.run("ipconfig", shell: :elevated)
 
 # Run a script on the remote host
 connection.run_script("/local/script.sh", "/remote/path/script.sh")

lib/remotus/core_ext/elevated.rb

@@ -5,13 +5,14 @@
 module Remotus
   # Core Ruby extensions
   module CoreExt
-    # Elevated extension module
+    # WinRM Elevated extension module
     module Elevated
       unless method_defined?(:connection_opts)
         #
-        #  Returns a hash into a safe method name that can be used for instance variables
+        # Returns a hash for the connection options from the interal
+        # WinRM::Shells::Powershell object
         #
-        # @return [Hash] Method name
+        # @return [Hash] internal WinRM::Shells::Powershell connection options
         #
         def connection_opts
           @shell.connection_opts
@@ -21,4 +22,14 @@ def connection_opts
   end
 end
 
-WinRM::Shells::Elevated.include(Remotus::CoreExt::Elevated)
+# @api private
+# Main WinRM module
+module WinRM
+  # Shells module (contains PowerShell, Elevated, etc.)
+  module Shells
+    # Elevated PowerShell class from winrm-elevated
+    class Elevated
+      include Remotus::CoreExt::Elevated
+    end
+  end
+end

lib/remotus/core_ext/string.rb

@@ -24,4 +24,8 @@ def to_method_name
   end
 end
 
-String.include(Remotus::CoreExt::String)
+# @api private
+# Core ruby string class
+class String
+  include Remotus::CoreExt::String
+end

lib/remotus/winrm_connection.rb

@@ -103,7 +103,7 @@ def port_open?
     # @param [String] command command to run
     # @param [Array] args command arguments
     # @param [Hash] options command options
-    # @param options [Symbol] :shell shell type to use for the connection
+    # @option options [Symbol] :shell shell type to use for the connection
     #
     # @return [Remotus::Result] result describing the stdout, stderr, and exit status of the command
     #
@@ -193,6 +193,9 @@ def restart_base_connection?
     #
     # Whether to restart the current WinRM connection
     #
+    # @param [Hash] options restart connection options
+    # @option options [Symbol] :shell shell type to use for the connection
+    #
     # @return [Boolean] whether to restart the current connection
     #
     def restart_connection?(**options)