Refactored Machine -> Board, made VM#nics behave like VM#io_buses, fi…

…xed docs.

Gemfile.lock

@@ -10,7 +10,7 @@ GEM
       git (>= 1.2.5)
       rake
       rdoc
-    json (1.6.6)
+    json (1.7.0)
     macaddr (1.5.0)
       systemu (>= 2.4.0)
     mechanize (2.4)
@@ -24,9 +24,9 @@ GEM
     metaclass (0.0.1)
     mime-types (1.18)
     minitest (2.12.1)
-    mocha (0.11.2)
+    mocha (0.11.3)
       metaclass (~> 0.0.1)
-    multi_json (1.3.2)
+    multi_json (1.3.4)
     net-http-digest_auth (1.2)
     net-http-persistent (2.6)
     nokogiri (1.5.2)

lib/virtual_box.rb

@@ -6,11 +6,11 @@ module VirtualBox
 require 'hashie/mash'
 require 'uuid'
 
+require 'virtual_box/board.rb'
 require 'virtual_box/cli.rb'
 require 'virtual_box/dhcp.rb'
 require 'virtual_box/disk.rb'
 require 'virtual_box/io_bus.rb'
-require 'virtual_box/machine.rb'
 require 'virtual_box/nic.rb'
 require 'virtual_box/version.rb'
 require 'virtual_box/vm.rb'

lib/virtual_box/machine.rb → lib/virtual_box/board.rb

@@ -2,83 +2,110 @@
 
 module VirtualBox
 
-# Configuration for a virtual machine.
-class Machine
-  # The number of CPUs in the VM.
+# Specification for a virtual machine's motherboard.
+class Board
+  # The number of CPUs (cores) on this board.
+  # @return [Integer]
   attr_accessor :cpus
 
-  # The amount of megabytes of RAM in the VM.
+  # The amount of megabytes of RAM on this board.
+  # @return [Integer]
   attr_accessor :ram
-  # The amount of megabytes of video RAM in the VM.
+  # The amount of megabytes of video RAM on this board's video card.
+  # @return [Integer]
   attr_accessor :video_ram
 
   # The UUID presented to the guest OS.
+  # @return [String]
   attr_accessor :hardware_id  
 
   # The OS that will be running in the virtualized VM.
   #
-  # This is used to improve the virtualization performance.
+  # Used to improve the virtualization performance.
+  # @return [Symbol]
   attr_accessor :os
 
   # Whether the VM supports PAE (36-bit address space).
+  # @return [Boolean]
   attr_accessor :pae  
   # Whether the VM supports ACPI.
+  # @return [Boolean]
   attr_accessor :acpi
   # Whether the VM supports I/O APIC.
   #
   # This is necessary for 64-bit OSes, but makes the virtualization slower.
+  # @return [Boolean]
   attr_accessor :io_apic
 
-  # Whether the VM attempts to use hardware support (Intel VT-x or AMD-V).
+  # Whether the VMM attempts to use hardware support (Intel VT-x or AMD-V).
   #
   # Hardware virtualization can increase VM performance, especially used in
   # conjunction with the other hardware virtualization options. However, using
-  # hardware virtualzation in conjunction with other hypervisors can crash the
+  # hardware virtualization in conjunction with other hypervisors can crash the
   # host machine.
+  # @return [Boolean]
   attr_accessor :hardware_virtualization
-  # Whether the VM uses hardware support for nested paging.
+  # Whether the VMM uses hardware support for nested paging.
   #
   # The option is used only if hardware_virtualization is set.
+  # @return [Boolean]
   attr_accessor :nested_paging
-  # Whether the VM uses hardware support for tagged TLB (VPID).
+  # Whether the VMM uses hardware support for tagged TLB (VPID).
   #
   # The option is used only if hardware_virtualization is set. 
+  # @return [Boolean]
   attr_accessor :tagged_tlb
 
   # Whether the VM supports 3D acceleration.
   #
   # 3D acceleration will only work with the proper guest extensions.
+  # @return [Boolean]
   attr_accessor :accelerate_3d
 
-  # Whether the BIOS logo will fade in when the VM boots.
+  # Whether the BIOS logo will fade in when the board boots.
+  # @return [Boolean]
   attr_accessor :bios_logo_fade_in
-  # Whether the BIOS logo will fade out when the VM boots.
+  # Whether the BIOS logo will fade out when the board boots.
+  # @return [Boolean]
   attr_accessor :bios_logo_fade_out
-  # The number of seconds to display the BIOS logo when the VM boots.
+  # The number of seconds to display the BIOS logo when the board boots.
+  # @return [Integer]
   attr_accessor :bios_logo_display_time
   # Whether the BIOS allows the user to temporarily override the boot VM device. 
   #
-  # If +false+, no override is allowed. Otherwise, the user can press F12 at
+  # If false, no override is allowed. Otherwise, the user can press F12 at
   # boot time to select a boot device. The user gets a prompt at boot time if
-  # the value is +true+. If the value is +:menu_only+ the user does not get a
-  # prompt, but can still press F12 to select a device.  
+  # the value is true. If the value is :menu_only the user does not get a
+  # prompt, but can still press F12 to select a device.
+  # @return [Boolean, Symbol]
   attr_accessor :bios_boot_menu  
   # Indicates the boot device search order for the VM's BIOS.
   #
-  # This is an array that can contain the following symbols: +:floppy+, +:dvd+,
-  # +:disk+, +:net+. Symbols should not be repeated.
+  # This is an array that can contain the following symbols: :floppy+, :dvd,
+  # :disk, :net. Symbols should not be repeated.
+  # @return [Array<Symbol>]
   attr_accessor :boot_order
 
   # If +true+, EFI firmware will be used instead of BIOS, for booting.
+  #
+  # The VirtualBox documentation states that EFI booting is highly experimental,
+  # and should only be used to virtualize MacOS.
+  # @return [Boolean]
   attr_accessor :efi
 
-  # Creates a VM configuration with the given attributes
+  # Creates a new motherboard specification based on the given attributes.
+  #
+  # @param Hash<Symbol, Object> options ActiveRecord-style initial values for
+  #     attributes; can be used together with Board#to_hash to save and restore
   def initialize(options = {})
     reset
     options.each { |k, v| self.send :"#{k}=", v }
   end  
 
   # Arguments to "VBoxManage modifyvm" describing the VM's general settings.
+  #
+  # @return [Array<String>] arguments that can be concatenated to a "VBoxManage
+  #     modifyvm" command
   def to_params
     params = []
     params.push '--cpus', cpus.to_s
@@ -122,6 +149,9 @@ def to_params
   end
 
   # Parses "VBoxManage showvminfo --machinereadable" output into this instance.
+  #
+  # @param [Hash<String, String>] output parsed by Vm.parse_machine_readble  
+  # @return [VirtualBox::Board] self, for easy call chaining
   def from_params(params)
     self.cpus = params['cpus'].to_i
     self.ram = params['memory'].to_i
@@ -163,6 +193,7 @@ def from_params(params)
   # Resets to default settings.
   #
   # The defaults are chosen somewhat arbitrarily by the gem's author.
+  # @return [VirtualBox::Board] self, for easy call chaining
   def reset
     self.cpus = 1
     self.ram = 512
@@ -186,9 +217,13 @@ def reset
     self.bios_boot_menu = false
 
     self.boot_order = [:disk, :net, :dvd]
+    self
   end
 
-  # Hash capturing this configuration. Can be passed to Machine#new.
+  # Hash capturing this motherboard specification. Can be passed to Board#new.
+  #
+  # @return [Hash<Symbol, Object>] Ruby-friendly Hash that can be used to
+  #                                re-create this motherboard specification
   def to_hash
     { :cpus => cpus, :ram => ram, :video_ram => video_ram,
       :hardware_id => hardware_id, :os => os, :pae => pae, :acpi => acpi,
@@ -203,8 +238,10 @@ def to_hash
 
   # The OS types supported by the VirtualBox installation.
   #
-  # A hash that maps symbols to the proper VirtualBox OS IDs, and also maps
-  # ID and description strings to symbols.
+  # @return [Hash<Symbol|String, String|Symbol>] mapping from
+  #     programmer-friendly symbols (e.g. :linux26) to proper VirtualBox OS IDs,
+  #     and from VirtualBox IDs and description strings to programmer-friendly
+  #     symbols
   def self.os_types
     return @os_types if @os_types
 
@@ -221,7 +258,8 @@ def self.os_types
 
   # Queries VirtualBox for available OS types.
   #
-  # Returns a hash mapping each type ID to its description.
+  # @return [Hash<String, String> mapping from each VirtualBox OS type ID to its
+  #     description
   def self.list_os_types
     result = VirtualBox.run_command ['VBoxManage', '--nologo', 'list',
                                      '--long', 'ostypes']
@@ -235,6 +273,6 @@ def self.list_os_types
     end
     Hash[types]
   end
-end  # class VirtualBox::Machine
+end  # class VirtualBox::Board
 
 end  # namespace VirtualBox

lib/virtual_box/io_bus.rb

@@ -2,11 +2,13 @@
 
 module VirtualBox
 
-# IO controller.
+# Specification for a IO controller attached to a virtual machine.
 class IoBus
-  # @return [String] controller name, unique inside a VM
+  # A user-friendly name for the I/O controller.
   #
+  # I/O controller names must be unique within the scope of a virtual machine.
   # VirtualBox uses "IDE Controller" and "SATA Controller" as default names.
+  # @return [String]
   attr_accessor :name
 
   # The kind of bus used by this controller.
@@ -121,6 +123,7 @@ def disks=(new_disks)
         @disks[[port, device]] = VirtualBox::Disk.new options
       end
     end
+    new_disks
   end
 
   # Parses "VBoxManage showvminfo --machinereadable" output into this instance.

lib/virtual_box/nic.rb

@@ -76,15 +76,13 @@ def initialize(options = {})
   # Arguments to "VBoxManage modifyvm" describing the NIC.
   #
   # @param [Number] nic_id the number of the card (1-4) connected to the host
-  # @return [Array<String>]
+  # @return [Array<String>] arguments that can be concatenated to a "VBoxManage
+  #     modifyvm" command to express this NIC specification
   def to_params(nic_id)
     params = []
 
     params.push "--nic#{nic_id}"
     case mode
-    when :none
-      params.push 'none'
-      return params
     when :nat
       params.push 'nat'
     when :bridged
@@ -139,13 +137,6 @@ def from_params(params, nic_id)
     when 'hostonly'
       self.mode = :host
       self.net_id = params["hostonlyadapter#{nic_id}"]    
-    when 'none'
-      self.mode = :none
-      self.chip = nil
-      self.net_id = nil
-      self.mac = nil
-      self.trace_file = nil
-      return      
     end
 
     self.chip = case params["nictype#{nic_id}"]