[Documentation] Start adding really basic documentation

.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+--private

lib/resolver/errors.rb

@@ -1,14 +1,22 @@
 module Resolver
+  # An error that occurred during the resolution process that holds the
+  # {#dependencies} that caused the error
   class ResolverError < StandardError
+    # The dependencies responsible for causing the error
     attr_reader :dependencies
+
+    # @param [Array] dependencies see {#dependencies}
     def initialize(message, *dependencies)
       require 'set'
       @dependencies = Set.new(dependencies)
       super message
     end
   end
 
+  # An error caused by attempting to fulfil a dependency that was circular
   class CircularDependencyError < ResolverError
+    # @param [DependencyGraph::Vertex] nodes the nodes in the dependency graph
+    #   that caused the error
     def initialize(*nodes)
       super "There is a circular dependency between #{nodes.map(&:name) * ' and '}",
         *nodes.map(&:payload)

lib/resolver/resolver.rb

@@ -1,17 +1,38 @@
 require 'resolver/dependency_graph'
 
 module Resolver
+  # This class encapsulates a dependency resolver.
+  # The resolver is responsible for determining which set of dependencies to
+  # activate, with feedback from the the
+  #
+  #
   class Resolver
     require 'resolver/resolution'
 
-    attr_reader :specification_provider, :resolver_ui
+    # @return [SpecificationProvider] the specification provider used
+    #   in the resolution process
+    attr_reader :specification_provider
 
+    # @return [UI] the UI module used to communicate back to the user
+    #   during the resolution process
+    attr_reader :resolver_ui
+
+    # @param  [SpecificationProvider] specification_provider
+    #   see {#specification_provider}
+    # @param  [UI] resolver_ui
+    #   see {#resolver_ui}
     def initialize(specification_provider, resolver_ui)
       @specification_provider = specification_provider
       @resolver_ui = resolver_ui
     end
 
-    def resolve(requested, base)
+    # Resolves the requested dependencies into a {DependencyGraph},
+    # locking to the base dependency graph (if specified)
+    # @param [Array] requested an array of 'requested' dependencies that the
+    #   {#specification_provider} can understand
+    # @param [DependencyGraph,nil] base the base dependency graph to which
+    #   dependencies should be 'locked'
+    def resolve(requested, base = DependencyGraph.new)
       Resolution.new(specification_provider,
                      resolver_ui,
                      requested,

lib/resolver/state.rb

@@ -1,4 +1,12 @@
 module Resolver
+  # A state that a {Resolution} can be in
+  # @attr [String] name
+  # @attr [Array] requirements
+  # @attr [DependencyGraph] activated
+  # @attr [Object] requirement
+  # @attr [Object] possibility
+  # @attr [Integer] depth
+  # @attr [Object] conflicts
   ResolutionState = Struct.new(
     :name,
     :requirements,
@@ -9,7 +17,12 @@ module Resolver
     :conflicts
   )
 
+  # A state that encapsulates a set of {#requirements} with an {Array} of
+  # possibilities
   class DependencyState < ResolutionState
+    # Removes a possibility from `self`
+    # @return [PossibilityState] a state with a single possibility,
+    #  the possibility that was removed from `self`
     def pop_possibility_state
       PossibilityState.new(
         name,
@@ -23,6 +36,8 @@ def pop_possibility_state
     end
   end
 
+  # A state that encapsulates a single possibility to fulfill the given
+  # {#requirement}
   class PossibilityState < ResolutionState
   end
 end