Updates documentation

Author: gstark

README.md renamed to README.rdoc

@@ -1,11 +1,13 @@
-# TeslaAPI
+= TeslaAPI
+
+== DESCRIPTION
 
 Allows access to the Tesla REST API for reading car telemetry and controlling basic
 vehicle features such as locking doors, opening the roof and controlling the AC system.
 
 Implements the API documented here: https://github.com/timdorr/model-s-api
 
-## Installation
+== Installation
 
 Add this line to your application's Gemfile:
 
@@ -19,7 +21,7 @@ Or install it yourself as:
 
     $ gem install tesla-api
 
-## Usage
+== Usage
 
     tesla = TeslaAPI::Connection.new("[email protected]", "password")
 
@@ -29,7 +31,7 @@ Or install it yourself as:
 
     puts mycar.drive_state.speed # => 65
 
-## Contributing
+== Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

lib/tesla-api.rb

@@ -1,6 +1,7 @@
 require 'json'
 require 'httpclient'
 
+require "tesla-api/tesla_api"
 require "tesla-api/version"
 require "tesla-api/private_api"
 require "tesla-api/connection"

lib/tesla-api/charge_state.rb

@@ -1,6 +1,68 @@
 module TeslaAPI
+
+  # Defines the current charge state of the vehicle
   class ChargeState < Data
-    def initialize(data)
+    ##
+    # :method: charging_state
+    # Charging state ("Complete", "Charging")
+
+    ##
+    # :method charging_to_max?
+    # true if currently performing a range charge
+
+    ##
+    # :method: battery_range_miles
+    # Rated miles for the current charge
+
+    ##
+    # :method: estimated_battry_range_miles
+    # Range estimated from current driving
+
+    ##
+    # :method: ideal_battery_range_miles
+    # Ideal range for the current charge
+
+    ##
+    # :method: battery_percentage
+    # Percentage of battery charge
+
+    ##
+    # :method: battery_current_flow
+    # Current flowing into the battery
+
+    ##
+    # :method: charger_voltage
+    # Current voltage being used to charge battery
+
+    ##
+    # :method: charger_pilot_amperage
+    # Max amperage allowed by the charger
+
+    ##
+    # :method: charger_actual_amperage
+    # Current amperage being drawn into battery
+
+    ##
+    # :method: charger_power
+    # Kilowatt of charger (rounded down)
+
+    ##
+    # :method: hours_to_full_charge
+    # Hours remaining until the vehicle is fully charged
+
+    ##
+    # :method: charge_rate_miles_per_hour
+    # Miles of range being added per hour
+
+    ##
+    # :method: charge_port_open?
+    # true if the charge port is open
+
+    ##
+    # :method: supercharging?
+    # true if charging via a Tesla SuperCharger
+
+    def initialize(data) # :nodoc:
       ivar_from_data("charging_state",               "charging_state",         data)
       ivar_from_data("charging_to_max",              "charge_to_max_range",    data)
       ivar_from_data("battery_range_miles",          "battery_range",          data)

lib/tesla-api/climate_state.rb

@@ -1,6 +1,44 @@
 module TeslaAPI
+  # Defines the climate state of the vehicle.
+  #
   class ClimateState < Data
-    def initialize(data)
+    ##
+    # :method: inside_temp_celcius
+    # Temperature (celcius) inside the vehicle
+
+    ##
+    # :method: outside_temp_celcius
+    # Temperature (celcius) outside the vehicle
+
+    ##
+    # :method: driver_temp_setting_celcius
+    # Temperature (celcius) the driver has set
+
+    ##
+    # :method: passenger_temp_setting_celcius
+    # Temperature (celcius) the passenger has set
+
+    ##
+    # :method: fan_speed
+    # 0 to 6 (or nil)
+
+    ##
+    # :method: auto_conditioning_on?
+    # true if auto air conditioning is on
+
+    ##
+    # :method: front_defroster_on?
+    # true if the front defroster is on
+
+    ##
+    # :method: rear_defroster_on?
+    # true if the rear defroster is on
+
+    ##
+    # :method: fan_on?
+    # true if the fan is on
+
+    def initialize(data) # :nodoc:
       ivar_from_data("inside_temp_celcius",            "inside_temp",            data)
       ivar_from_data("outside_temp_celcius",           "outside_temp",           data)
       ivar_from_data("driver_temp_setting_celcius",    "driver_temp_setting",    data)

lib/tesla-api/connection.rb

@@ -1,12 +1,21 @@
 module TeslaAPI
+  # Connection object to the Tesla Model S HTTP API endpoint.
   class Connection
     include PrivateAPI
 
-    attr_reader :email, :password
+    # email address of logged in user
+    attr_reader :email
 
-    HOST           = "https://portal.vn.teslamotors.com"
+    # password of logged in user
+    attr_reader :password
+
+    # Host for status/command related API
+    HOST = "https://portal.vn.teslamotors.com"
+
+    # Host for streaming API
     STREAMING_HOST = "https://streaming.vn.teslamotors.com"
 
+    # Supply the email and password for login to teslamotors.com
     def initialize(email, password)
       @email    = email
       @password = password
@@ -17,25 +26,30 @@ def initialize(email, password)
       login(email, password)
     end
 
+    # Call to see all HTTP traffic to and from the API
     def debug!
       @client.debug_dev = STDOUT
     end
 
+    # Convenience method to return the first Vehicle
     def vehicle
       vehicles.first
     end
 
+    # Returns Vehicle objects for all vehicles the account contains
     def vehicles
       @vehicles ||= begin
         _, json = get_json("/vehicles")
         json.map { |data| Vehicle.new(self, data) }
       end
     end
 
+    # Force the vehicles to reload (in case some of the data has changed)
     def reload!
       @vehicles = nil
     end
 
+    # Logged into the API
     def logged_in?
       @logged_in
     end

lib/tesla-api/data.rb

@@ -1,41 +1,47 @@
 module TeslaAPI
+  # Base class for all data responses from the HTTP API
+  #
+  # Defines an instance_variable? method for each instance_variable defined allowing for
+  # methods such as __________?
+  #
+  # Also overrides #inspect to elimiante the back reference to the connection object
   class Data
-    def method_missing(method_name, *args, &block)
+    def method_missing(method_name, *args, &block) # :nodoc:
       if has_query_ivar_method?(method_name)
         instance_variable_get(instance_var)
       else
         super(symbol, *args, &block)
       end
     end
 
-    def respond_to_missing?(method_name, include_private = false)
+    def respond_to_missing?(method_name, include_private = false) # :nodoc:
       has_query_ivar_method?(method_name) || super
     end
 
-    def inspect
+    def inspect # :nodoc:
       "#<#{self.class.name}:0x#{self.object_id.to_s(16)} #{inspect_ivars}>"
     end
 
-    def ivar_from_data(name, data_key, data)
+    def ivar_from_data(name, data_key, data) # :nodoc:
       instance_variable_set("@#{name}".to_sym, data[data_key])
 
       self.class.send(:attr_reader, name.to_sym)
     end
 
     protected
 
-    def has_query_ivar_method?(method_name)
+    def has_query_ivar_method?(method_name) # :nodoc:
       method = method_name.to_s
       instance_var = "@#{method.gsub(/\?$/,"")}".to_sym
 
       method =~ /(.+)\?/ && instance_variables.include?(instance_var)
     end
 
-    def inspect_ivars
+    def inspect_ivars # :nodoc:
       ivars_for_inspect.map { |ivar| "#{ivar}=#{instance_variable_get(ivar)}" }.join(" ")
     end
 
-    def ivars_for_inspect
+    def ivars_for_inspect # :nodoc:
       (instance_variables - [:@tesla])
     end
   end

lib/tesla-api/drive_state.rb

@@ -1,8 +1,30 @@
 module TeslaAPI
+  # Data defining the driving state of the the vehicle
   class DriveState < Data
+    # Time when GPS data was recorded
     attr_reader :gps_timestamp
 
-    def initialize(data)
+    ##
+    # :method: shift_state
+    # Unknown
+
+    ##
+    # :method: speed
+    # Vehicle speed (units?)
+
+    ##
+    # :method: latitude
+    # Lattitude of vehicle
+
+    ##
+    # :method: longitude
+    # Longitude of vehicle
+
+    ##
+    # :method: heading
+    # Compass heading (0 to 360) degrees
+
+    def initialize(data) # :nodoc:
       ivar_from_data("shift_state", "shift_state", data)
       ivar_from_data("speed",       "speed",       data)
       ivar_from_data("latitude",    "latitude",    data)

lib/tesla-api/errors.rb

@@ -1,31 +1,40 @@
 module TeslaAPI
-  class InvalidJSON < StandardError
-    attr_reader :error
-
-    def initialize(error)
-      @error = error
+  # Exceptions thrown by the TeslaAPI
+  module Errors
+    # JSON cannot be parsed
+    class InvalidJSON < StandardError
+      # JSON parsing error details
+      attr_reader :error
+
+      def initialize(error) # :nodoc:
+        @error = error
+      end
+
+      def to_s # :nodoc:
+        error.to_s
+      end
     end
 
-    def to_s
-      error.to_s
+    # Thrown when the action requires a logged in connection
+    class NotLoggedIn < StandardError
     end
-  end
-
-  class NotLoggedIn < StandardError
-  end
 
-  class APIFailure < StandardError
-  end
+    # Thrown when the API returns a failure state
+    class APIFailure < StandardError
+    end
 
-  class InvalidResponse < StandardError
-    attr_reader :response
+    # Thrown when the response is invalid (non 200-OK HTTP result)
+    class InvalidResponse < StandardError
+      # Response object from httpclient
+      attr_reader :response
 
-    def initialize(response)
-      @response = response
-    end
+      def initialize(response) # :nodoc:
+        @response = response
+      end
 
-    def to_s
-      "Invalid Response: #{response.inspect}"
+      def to_s # :nodoc:
+        "Invalid Response: #{response.inspect}"
+      end
     end
   end
 end

lib/tesla-api/gui_settings.rb

@@ -1,10 +1,28 @@
 module TeslaAPI
+  # Defines the current user settings for the vehicle's graphical display
   class GUISettings < Data
+    ##
+    # :method: gui_distance_units
+    # Units ("mi", "hr") for showing range
+
+    ##
+    # :method: gui_temperature_units
+    # Units ("F", "C") for showing temperaturs
+
+    ##
+    # :method: gui_charge_rate_units
+    # Units ("mi", "hr") for showing charge rage
+
+    ##
+    # :method: gui_range_display
+    # Units ("Rated", "Ideal") for showing range
+
+    # true if the UI show 24 hour time (e.g. 17:45)
     def gui_24_hour_time?
       @gui_24_hour_time
     end
 
-    def initialize(data)
+    def initialize(data) # :nodoc:
       ivar_from_data("gui_distance_units",    "gui_distance_units",    data)
       ivar_from_data("gui_temperature_units", "gui_temperature_units", data)
       ivar_from_data("gui_charge_rate_units", "gui_charge_rate_units", data)