Merge pull request #51 from site5/refactor/tomdoc

RDoc => TomDoc

Author: jmazzi

.document

@@ -8,3 +8,5 @@ Gemfile.lock
 
 .rvmrc
 .rbenv-version
+
+/.yardoc/*

.gitignore

@@ -1,4 +1,5 @@
 source "http://rubygems.org"
 
-# Specify your gem's dependencies in lol.gemspec
+gem 'rake-tomdoc', github: 'site5/rake-tomdoc'
+
 gemspec

Gemfile

@@ -6,10 +6,13 @@ This library was first created for internal use at [Site5 LLC][].
 
 SolusVM has been tested on MRI 1.9.2, MRI 1.9.3 and 1.9-compatible JRuby.
 
+Documentation is available in [TomDoc][] format.
+
 [Site5 LLC]: http://www.site5.com
 [SolusVM Admin::API]: http://wiki.solusvm.com/index.php/API:Admin
 [Build Status]: http://travis-ci.org/site5/solusvm
 [Build Icon]: https://secure.travis-ci.org/site5/solusvm.png?branch=master
+[TomDoc]: http://site5.github.io/solusvm/
 
 Basic Examples
 --------------
@@ -131,12 +134,9 @@ The command line utility, solusvm, will look for a .solusvm.yml file in ~/. You
 Requirements
 ------------
 
-* xml-simple
-
-Documentation
--------------
-
-* http://solusvm.rubyforge.org/solusvm/
+* [xml-simple](https://github.com/maik/xml-simple)
+* [thor](https://github.com/erikhuda/thor)
+* [faraday](https://github.com/lostisland/faraday)
 
 Installation
 ------------
@@ -146,11 +146,9 @@ Installation
 Contributors
 ------------
 
-* [Justin Mazzi](http://github.com/jmazzi)
-* [Maran H.](http://github.com/maran)
-* [Joshua Priddle](http://github.com/itspriddle)
-* [Vince Stratful](http://github.com/Vincepbell)
-* [Rubem Nakamura](http://github.com/rubemz)
+SolusVM was originall written by [jmazzi](https://github.com/site5/jmazzi) for
+internal use at Site5 LLC. Additional contributors are [listed on
+GitHub](https://github.com/site5/solusvm/graphs/contributors).
 
 Note on Patches/Pull Requests
 -----------------------------

README.markdown

@@ -1,8 +1,8 @@
 require 'rubygems'
 require 'rake'
 require 'bundler/gem_tasks'
-
 require 'rake/testtask'
+require 'rake-tomdoc'
 
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
@@ -23,21 +23,5 @@ rescue LoadError
   end
 end
 
-begin
-  require 'rdoc/task'
-  Rake::RDocTask.new do |rdoc|
-    version = Solusvm::VERSION
-
-    rdoc.rdoc_dir = 'rdoc'
-    rdoc.title = "solusvm #{version}"
-    rdoc.rdoc_files.include('README*')
-    rdoc.rdoc_files.include('lib/**/*.rb')
-  end
-rescue LoadError
-  task :rdoc do
-    abort "rdoc is not available. In order to run rdoc, you must: sudo gem install rdoc"
-  end
-end
-
 task :default => :test
 task :spec => :test

Rakefile

@@ -9,19 +9,24 @@ def initialize(config = {})
       @config = config
     end
 
-    # Prepares and sends the API request to the URL specificed in Solusvm.config
+    # Public: Prepares and sends the API request to the URL specified in
+    # `Solusvm.config`.
     #
-    #  class MyClass < Base
-    #    def create_server(name)
-    #      perform_request(:action => "name", :id => 1)
-    #    end
-    #  end
+    # options     - A Hash of options. Any options not listed below are
+    #               converted to HTTP query arguments and are passed along to
+    #               the API.
+    #               :action - Specifies which API method to execute
+    # force_array - see parse_response
     #
-    # Options:
-    # * <tt>:action</tt> - Specifies which API method to execute
-    # All other options passed in are converted to http query arguments and are passed along to the API
+    # Example
     #
-    # <tt>force_array</tt> - see parse_response
+    #     class MyClass < Base
+    #       def create_server(name)
+    #         perform_request(:action => "name", :id => 1)
+    #       end
+    #     end
+    #
+    # Returns true if the request was successful.
     def perform_request(options = {}, force_array = false)
       options.reject! {|_,v| v.nil? }
 
@@ -32,23 +37,34 @@ def perform_request(options = {}, force_array = false)
       successful?
     end
 
-    # Creates a Faraday connection and returns it.
+    # Public: Creates a Faraday connection.
+    #
+    # Returns a Faraday::Connection.
     def conn
       @conn ||= Faraday.new(ssl: ssl_option) do |c|
         c.request :retry if @config.fetch(:retry_request, false)
         c.adapter :net_http
       end
     end
 
+    # Public: SSL options used when creating a Faraday connection.
+    #
+    # Returns a Hash.
     def ssl_option
-      ca_path  = File.join(File.dirname(__FILE__), "..", "cacert.pem")
-      {verify: true, ca_file: File.expand_path(ca_path)}
+      {
+        verify: true,
+        ca_file: File.expand_path("../../cacert.pem", __FILE__)
+      }
     end
 
-    # Converts the XML response to a Hash
+    # Public: Converts the XML response to a Hash.
     #
-    # <tt>force_array</tt> - Parses the xml element as an array; can be a string with the element name
-    #     or an array with element names
+    # status      - Faraday::Response#status
+    # body        - Faraday::Response#body
+    # force_array - Parses the xml element as an array; can be a string with
+    #               the element name or an array with element names
+    #
+    # Returns a Hash.
     def parse_response(status, body, force_array = false)
       parse_error(status, body) || begin
         force_array = Array(force_array) if force_array
@@ -57,14 +73,23 @@ def parse_response(status, body, force_array = false)
       end
     end
 
-    # Parses a returned_parameters value as a list, if present.
+    # Public: Parses a returned_parameters value as a list, if present.
+    #
+    # attribute - The attribute to check
+    #
+    # Returns an Array or nil.
     def parse_returned_params_as_list(attribute)
       if returned_parameters[attribute] && !returned_parameters[attribute].empty?
         returned_parameters[attribute].to_s.split(",")
       end
     end
 
-    # Parses error responses.
+    # Public: Parses error responses.
+    #
+    # status - HTTP status code
+    # body   - Raw body
+    #
+    # Returns a Hash or nil.
     def parse_error(status, body)
       if (200..299).include?(status)
         # Checks for application errors
@@ -81,49 +106,65 @@ def parse_error(status, body)
       end
     end
 
-    # Returns true when a request has been successful
+    # Public: Check if the request was successful.
+    #
+    #     my_class = MyClass.new
+    #     my_class.create_server("example.com")
+    #     my_class.successful? # => true
     #
-    #   my_class = MyClass.new
-    #   my_class.create_server("example.com")
-    #   my_class.successful? # => true
+    # Returns true if the request was successful.
     def successful?
       returned_parameters["status"].nil? || returned_parameters["status"] == "success"
     end
 
-    # Returns the API endpoint set in the instance configuration. Otherwise,
-    # it returns the default configuration.
+    # Public: Returns the API endpoint set in the instance configuration.
+    # Otherwise, it returns the default configuration.
     #
     # Returns a String
     def api_endpoint
       @config.fetch(:url)
     end
 
-    # Returns the API id set in the instance configuration. Otherwise,
+    # Public: Returns the API id set in the instance configuration. Otherwise,
     # it returns the default configuration.
     #
     # Returns a String
     def api_id
       @config.fetch(:api_id)
     end
 
-    # Returns the API key set in the instance configuration. Otherwise,
-    # it returns the default configuration.
+    # Public: Returns the API key set in the instance configuration.
+    # Otherwise, it returns the default configuration.
     #
-    # Returns a String
+    # Returns a String.
     def api_key
       @config.fetch(:api_key)
     end
 
+    # Public: API options
+    #
+    # option - Key to fetch
+    #
+    # Returns the given option.
     def api_options(option)
       if options = @config[:options]
         options[option.to_sym]
       end
     end
 
+    # Public: API login information.
+    #
+    # Returns a Hash.
     def api_login
-      {id: api_id, key: api_key}
+      { id: api_id, key: api_key }
     end
 
+    # Public: Logs API actions to the configured logger.
+    #
+    # options - A Hash of options
+    #           :action - the API action
+    #
+    # Returns nothing.
     def log_messages(options)
       logger, logger_method = api_options(:logger), api_options(:logger_method)
 
@@ -136,12 +177,20 @@ def log_messages(options)
       end
     end
 
-    # API response message
+    # Public: API response message
+    #
+    # Returns a String.
     def statusmsg
       returned_parameters["statusmsg"]
     end
 
-    # Validates the server type.
+    # Public: Validates the server type.
+    #
+    # type - The server type to check
+    #
+    # Yields a required block if given server type is valid.
+    #
+    # Returns the result of the block, or false if the server type is invalid.
     def validate_server_type(type, &block)
       type = type.strip
 

lib/solusvm/base.rb

@@ -1,43 +1,65 @@
 module Solusvm
   # Solusvm::Client is the class for working with clients.
   class Client < Base
-    # Creates a client.
+    # Public: Creates a client.
     #
-    # Options:
+    # options - A Hash of options:
+    #           :username
+    #           :password
+    #           :email
+    #           :firstname
+    #           :lastname
+    #           :company
     #
-    # * <tt>:username</tt>
-    # * <tt>:password</tt>
-    # * <tt>:email</tt>
-    # * <tt>:firstname</tt>
-    # * <tt>:lastname</tt>
-    # * <tt>:company</tt>
-    def create(options ={})
+    # Returns a Hash with the new client info, or false if the client was not
+    # created successfully.
+    def create(options = {})
       perform_request(options.merge(action: 'client-create')) && returned_parameters
     end
 
-    # Change client password for the solus admin.
+    # Public: Change client password for the Solus admin.
+    #
+    # username     - The client's username
+    # new_password - The new password
+    #
+    # Returns true if the client's password was successfully changed.
     def change_password(username, new_password)
-      perform_request({action: "client-updatepassword", username: username, password: new_password})
+      perform_request(action: "client-updatepassword", username: username, password: new_password)
     end
 
-    # Checks wether a specific client exists.
+    # Public: Checks if a specific client exists.
+    #
+    # username - The client's username
+    #
+    # Returns true if the client exists.
     def exists?(username)
-      perform_request({action: 'client-checkexists', username: username})
+      perform_request(action: 'client-checkexists', username: username)
     end
 
-    # Verify a clients login. Returns true when the specified login is correct.
+    # Public: Verify a client's login.
+    #
+    # username - The client's username
+    # password - The client's password
+    #
+    # Returns true if the given credentials are correct.
     def authenticate(username, password)
-      perform_request({action: 'client-authenticate', username: username, password: password})
+      perform_request(action: 'client-authenticate', username: username, password: password)
     end
 
-    # Deletes an existing client.
+    # Public: Deletes an existing client.
+    #
+    # username - The client's username
+    #
+    # Returns true if the client was successfully deleted.
     def delete(username)
-      perform_request({action: "client-delete", username: username})
+      perform_request(action: "client-delete", username: username)
     end
 
-    # Lists existing clients.
+    # Public: Lists existing clients.
+    #
+    # Returns an Array.
     def list
-      perform_request({action: "client-list"}, "client")
+      perform_request({ action: "client-list" }, "client")
 
       if returned_parameters["clients"] && returned_parameters["clients"]["client"]
         returned_parameters["clients"]["client"]