frecon 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3695507c98a8055222ee241b01a4811d02f0aa96
-  data.tar.gz: 152e3d581b3f941762b1cba4b6dfb871408b042d
+  metadata.gz: 4e2c810e2a8cf4f910ac9a90d52a449b61285df9
+  data.tar.gz: 8a3f9339a0b6539ec355458f8e1b9e7aa3a995da
 SHA512:
-  metadata.gz: e8da7107dd168433d62a49c08104e3c4f675543e0837c6c3041b67edcfd78710ea2b9ec3c0608f46ac4fc2c39269c005e4536258bd6a17be324cea4f6502757b
-  data.tar.gz: f9811d2b31a5c30fc0597a9357be77122df2d052686857e506a7945b0e85b8635e7626e14b4b1f7312e3774c464508b23c2b6bdc62056609905d35251aa9ca7c
+  metadata.gz: 52ce69ae4af6d7137426fd79a6ea39deffdc0d71900a18cbff137ee986a6ff74dfad0aad45284dbc5840629670088e9b1c8c5a50911822382d354a7b843d22ed
+  data.tar.gz: 362cea6a6e6110246ba69320b856d9439c52c0c14c659734f61eeb78fadc0f5bbdb25127239b10bd3ffc9646498ca0f5cffc780fba4ccda21db6883b30ad8152

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Dependencies loaded from frecon.gemspec
+gemspec

data/Rakefile

@@ -0,0 +1,15 @@
+require "yard"
+
+YARD::Config.load_plugin('tomdoc')
+YARD::Config.load_plugin('mongoid')
+
+namespace :docs do
+	YARD::Rake::YardocTask.new :generate do |task|
+		task.files = ['lib/**/*.rb', 'bin/**/*']
+	end
+
+	YARD::Rake::YardocTask.new :list_undoc do |task|
+		task.files = ['lib/**/*.rb', 'bin/**/*']
+		task.stats_options = ['--list-undoc']
+	end
+end

data/lib/frecon.rb

@@ -11,10 +11,20 @@ require "mongoid"
 
 require "frecon/base"
 
+require "frecon/controller"
+require "frecon/controllers"
+require "frecon/model"
+require "frecon/models"
+require "frecon/scraper"
+require "frecon/scrapers"
+
 require "frecon/configuration"
 require "frecon/configuration_file"
+require "frecon/match_number"
+require "frecon/position"
+require "frecon/request_error"
+require "frecon/routes"
+
 require "frecon/database"
 require "frecon/server"
 require "frecon/console"
-
-require "frecon/scrapers"

data/lib/frecon/base/bson.rb

@@ -7,8 +7,17 @@
 # license with this program.  If not, please see
 # <http://opensource.org/licenses/MIT>.
 
+# Public: An extension for the BSON module.
 module BSON
+	# Public: A monkey-patch for the BSON::ObjectId class which introduces an
+	# #as_json method.
 	class ObjectId
+		# Public: Get produce a JSON representation of this ObjectId.
+		#
+		# Since we don't want to produce a JSON Object for every ID, this method
+		# instead just returns the String _id value within this object.
+		#
+		# Returns a String containing the value of this ObjectId.
 		def as_json(*args)
 			to_s
 		end

data/lib/frecon/base/variables.rb

@@ -7,15 +7,23 @@
 # license with this program.  If not, please see
 # <http://opensource.org/licenses/MIT>.
 
+# Public: The FReCon API module.
 module FReCon
-	VERSION ||= "0.5.0"
+	# Public: A String representing the current version of FReCon.
+	VERSION = "0.5.2"
 
 	@environment_variable = :development
 
+	# Public: Returns the current environment.
 	def self.environment
 		@environment_variable
 	end
 
+	# Public: Sets the environment.
+	#
+	# arg - The new environment.
+	#
+	# Returns the result from setting the current environment.
 	def self.environment=(arg)
 		@environment_variable = arg
 	end

data/lib/frecon/configuration.rb

@@ -10,13 +10,23 @@
 require "frecon/configuration_file"
 
 module FReCon
+	# Public: A wrapper to allow the manipulation of configurations.
 	class Configuration < Hash
+		# Public: Initialize a Configuration.
+		#
+		# data - a Hash representing the data.
 		def initialize(data)
 			data.each do |key, value|
 				self[key] = value
 			end
 		end
 
+		# Public: Convert self to a Hash.
+		#
+		# Recursively converts instances of Configuration within self
+		# to hashes by calling this method.
+		#
+		# Returns a Hash representing self.
 		def to_h
 			hash = {}
 
@@ -32,6 +42,11 @@ module FReCon
 			hash
 		end
 
+		# Public: Merge with another Configuration.
+		#
+		# Sets all key-value pairs within Configuration to the same within self.
+		#
+		# other - A Configuration or Hash to be merged with.
 		def merge(other)
 			case other
 			when Configuration, Hash
@@ -49,11 +64,20 @@ module FReCon
 			end
 		end
 
+		# Public: Constructs a configuration.
+		#
+		# options - A Hash containing various configurations.
+		#           :default_configuration  - The default configuration's values
+		#           :system_configuration   - The system's configuration's values
+		#           :user_configuration     - The user's configuration's values
+		#           :argument_configuration - The configuration values from command-line arguments
+		#
+		# Returns a Configuration generated by merging all of the given
+		# configurations together.
 		def self.construct!(default_configuration: ConfigurationFile.default.read,
 		                    system_configuration: ConfigurationFile.system.read,
 		                    user_configuration: ConfigurationFile.user.read,
 		                    argument_configuration: nil)
-
 			configuration_hierarchy = [default_configuration, system_configuration, user_configuration, argument_configuration]
 
 			configuration = Configuration.new({})

data/lib/frecon/configuration_file.rb

@@ -11,13 +11,23 @@ require "yaml"
 require "frecon/configuration"
 
 module FReCon
+	# Public: A class to handle configuration files.
 	class ConfigurationFile
+		# Public: The filename for the file.
 		attr_accessor :filename
 
+		# Public: Initialize a ConfigurationFile.
+		#
+		# filename - The name of the file.
 		def initialize(filename)
 			@filename = filename
 		end
 
+		# Public: Read from the file and generate a Configuration
+		# from the YAML data therein.
+		#
+		# Returns a Configuration representing the file's data or nil if it didn't
+		# exist.
 		def read
 			begin
 				data = open(@filename, "rb") do |io|
@@ -30,16 +40,22 @@ module FReCon
 			end
 		end
 
+		# Public: Create a new ConfigurationFile corresponding to the default
+		# defaults configuration location.
 		def self.default
 			self.new(File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "config", "default.yml")))
 		end
 
+		# Public: Create a new ConfigurationFile corresponding to the default
+		# system configuration location.
 		def self.system
 			self.new(File.join("", "etc", "frecon", "config.yml"))
 		end
 
+		# Public: Create a new ConfigurationFile corresponding to the default
+		# user configuration location.
 		def self.user
-			self.new(File.join(Dir.home, "config", "frecon.yml"))
+			self.new(File.join(Dir.home, ".config", "frecon.yml"))
 		end
 	end
 end

data/lib/frecon/console.rb

@@ -13,11 +13,17 @@ require "frecon/database"
 require "frecon/server"
 
 module FReCon
+	# Public: The wrapper system for a pry console.
 	class Console
+		# Public: Starts the FReCon console.
+		#
+		# :configuration - The Configuration to use when starting the console.
+		#
+		# Returns the result of running pry on FReCon.
 		def self.start(configuration: Configuration.construct!)
 			environment = configuration["frecon"]["console"]["environment"]
 			mongoid = configuration["frecon"]["database"]["mongoid"]
-			Database.setup(environment: environment, mongoid: mongoid)
+			Database.setup(environment, mongoid)
 
 			require "pry"
 

data/lib/frecon/controller.rb

@@ -10,30 +10,54 @@
 require "frecon/base"
 
 module FReCon
+	# Public: A base class to represent a controller.
 	class Controller
+		# Public: Converts the class's name to a Model name.
+		#
+		# Returns a Symbol that is the Model name.
 		def self.model_name
 			# Removes the namespace "FReCon::" and "Controller" from
 			# the class name, then singularizes the result.
 			self.name.gsub(/FReCon::|Controller\Z/, "").singularize
 		end
 
+		# Public: Converts the class's name to a Model.
+		#
+		# Returns the Model's class.
 		def self.model
 			# Removes the trailing "Controller" from the class name,
 			# singularizes the result, and turns it into the class.
 			self.name.gsub(/Controller\Z/, "").singularize.constantize
 		end
 
-		# Some models have to find themselves in special ways,
-		# so this can be overridden with those ways.
+		# Public: Find a model.
+		#
+		# params - A Hash containing the parameters.  This should contain an
+		#          'id' key, which is deleted and used for the find.
+		#
+		# Returns either the found model value or nil.
 		def self.find_model(params)
 			model.find params.delete("id")
 		end
 
-		# The 404 error message.
+		# Public: Generate a could-not-find message.
+		#
+		# value     - The value that was tested.
+		# attribute - The attribute that was used for the search.
+		# model     - The model that the search was performed upon.
+		#
+		# Returns a String containing the error message.
 		def self.could_not_find(value, attribute = "id", model = model_name.downcase)
 			"Could not find #{model} of #{attribute} #{value}!"
 		end
 
+		# Public: Process a JSON request.
+		#
+		# request - The internal Sinatra request object that is available to
+		#           request handling.
+		#
+		# Returns a Hash corresponding to the request's body.
+		# Raises a RequestError if the JSON parse fails.
 		def self.process_json_request(request)
 			# Rewind the request body (an IO object)
 			# in case someone else has already played
@@ -49,6 +73,20 @@ module FReCon
 			post_data
 		end
 
+		# Public: Process a creation request (HTTP POST)
+		#
+		# If `post_data` is an Array, iterates through the array and calls itself
+		# with each element within.  Otherwise, performs the creation using
+		# the attribute key-value pairings within the `post_data`.
+		#
+		# request   - The internal Sinatra request object that is available to
+		#             request handling.
+		# params    - The internal params Hash that is available to request
+		#             handling.
+		# post_data - The data that was sent in the request body.
+		#
+		# Returns an Array, a formatted response that can be passed back through
+		#   Sinatra's request processing.
 		def self.create(request, params, post_data = nil)
 			post_data ||= process_json_request request
 
@@ -85,6 +123,19 @@ module FReCon
 			end
 		end
 
+		# Public: Process an update request (HTTP PUT)
+		#
+		# Processes the JSON request, finds the model, then updates it.
+		#
+		# request   - The internal Sinatra request object that is available to
+		#             request handling.
+		# params    - The internal params Hash that is available to request
+		#             handling.
+		# post_data - The data that was sent in the request body.
+		#
+		# Returns a String with the JSON representation of the model.
+		# Raises a RequestError if the request is malformed or if the attributes
+		#   can't be updated.
 		def self.update(request, params, post_data = nil)
 			raise RequestError.new(400, "Must supply a #{model_name.downcase} id!") unless params[:id]
 
@@ -101,6 +152,19 @@ module FReCon
 			end
 		end
 
+		# Public: Process a deletion request (HTTP DELETE)
+		#
+		# Processes the JSON request, finds the model, then deletes it.
+		#
+		# request   - The internal Sinatra request object that is available to
+		#             request handling.
+		# params    - The internal params Hash that is available to request
+		#             handling.
+		# post_data - The data that was sent in the request body.
+		#
+		# Returns 204 if successful.
+		# Raises a RequestError if the request is malformed or if the model can't be
+		#   destroyed
 		def self.delete(params)
 			@model = find_model params
 
@@ -115,6 +179,20 @@ module FReCon
 			end
 		end
 
+		# Public: Process a show request (HTTP GET) for a specific instance of a
+		# model.
+		#
+		# Processes the JSON request, finds the model, then shows it.
+		#
+		# request   - The internal Sinatra request object that is available to
+		#             request handling.
+		# params    - The internal params Hash that is available to request
+		#             handling.
+		# post_data - The data that was sent in the request body.
+		#
+		# Returns a String with the JSON representation of the model.
+		# Raises a RequestError if the request is malformed or if the model can't be
+		#   found.
 		def self.show(params)
 			@model = find_model params
 
@@ -125,6 +203,19 @@ module FReCon
 			end
 		end
 
+		# Public: Process an index request (HTTP GET) for all instances of a model.
+		#
+		# Processes the JSON request, and returns a filtered list of all of the
+		# models.
+		#
+		# request   - The internal Sinatra request object that is available to
+		#             request handling.
+		# params    - The internal params Hash that is available to request
+		#             handling.
+		# post_data - The data that was sent in the request body.
+		#
+		# Returns a String with the JSON representation of the list of models.
+		# Raises a RequestError if the request is malformed.
 		def self.index(params)
 			if params.empty?
 				@models = model.all

data/lib/frecon/controllers/competitions_controller.rb

@@ -11,6 +11,7 @@ require "json"
 require "frecon/models/competition"
 
 module FReCon
+	# Public: The Competitions controller.
 	class CompetitionsController < Controller
 	end
 end

data/lib/frecon/controllers/dump_controller.rb

@@ -11,7 +11,11 @@ require "json"
 require "frecon/models"
 
 module FReCon
+	# Public: The Dump controller.
 	class DumpController
+		# Public: Creates a dump.
+		#
+		# Returns a String containing a dump of the database.
 		def self.full(params)
 			dump = {}
 
@@ -30,6 +34,14 @@ module FReCon
 			dump.to_json
 		end
 
+		# Public: Converts a Model's name to a dump-compliant name.
+		#
+		# Examples
+		#
+		#   DumpController.dump_compliant_name(FReCon::Team)
+		#   # => "teams"
+		#
+		# Returns a dump-compliant string.
 		def self.dump_compliant_name(model)
 			model.name.gsub(/FReCon::/, "").downcase.pluralize
 		end

data/lib/frecon/controllers/matches_controller.rb

@@ -11,6 +11,7 @@ require "json"
 require "frecon/models/match"
 
 module FReCon
+	# Public: The Matches controller.
 	class MatchesController < Controller
 	end
 end

data/lib/frecon/controllers/participations_controller.rb

@@ -11,6 +11,7 @@ require "json"
 require "frecon/models/participation"
 
 module FReCon
+	# Public: The Participations controller.
 	class ParticipationsController < Controller
 	end
 end

data/lib/frecon/controllers/records_controller.rb

@@ -11,6 +11,7 @@ require "json"
 require "frecon/models/record"
 
 module FReCon
+	# Public: The Records controller.
 	class RecordsController < Controller
 	end
 end

data/lib/frecon/controllers/robots_controller.rb

@@ -11,6 +11,7 @@ require "json"
 require "frecon/models/robot"
 
 module FReCon
+	# Public: The Robots controller.
 	class RobotsController < Controller
 	end
 end

data/lib/frecon/controllers/teams_controller.rb

@@ -8,10 +8,10 @@
 # <http://opensource.org/licenses/MIT>.
 
 require "json"
-require "frecon/base"
 require "frecon/models/team"
 
 module FReCon
+	# Public: The Teams controller.
 	class TeamsController < Controller
 	end
 end

data/lib/frecon/database.rb

@@ -18,8 +18,16 @@ require "yaml"
 require "frecon/models"
 
 module FReCon
+	# Public: A system to set up the database.
 	class Database
-		def self.setup(environment: FReCon.environment, mongoid: nil)
+		# Public: Set up the database.
+		#
+		# environment - Symbol containing environment to start the database in.
+		# mongoid     - Hash containing the configuration for Mongoid. If not
+		#               present, the lib/frecon/mongoid.yml file is given to
+		#               Mongoid.load!.  If present, the Hash is dumped to a
+		#               tempfile which is given to Mongoid.load!.
+		def self.setup(environment = FReCon.environment, mongoid = nil)
 			if mongoid.is_a?(Hash)
 				mongoid_tempfile = Tempfile.new("FReCon")
 

data/lib/frecon/match_number.rb

@@ -10,13 +10,46 @@
 require "frecon/base"
 
 module FReCon
+	# Public: A wrapper to handle converting match numbers and storing them.
 	class MatchNumber
+		# Public: All of the possible match types for a MatchNumber to have.
 		POSSIBLE_TYPES = [:practice, :qualification, :quarterfinal, :semifinal, :final]
-		ELIMINATION_TYPES = [:quarterfinal, :semifinal, :final]
 
-		attr_reader :number, :round
+		# Public: All of the elimination types for a MatchNumber to have.
+		ELIMINATION_TYPES = [:quarterfinal, :semifinal, :final]
 
-		# MongoDB compatibility methods.
+		# Public: The numerical part of the match number
+		#
+		# Examples
+		#
+		#   match_number = MatchNumber.new('qm2')
+		#   match_number.number
+		#   # => 2
+		attr_reader :number
+
+		# Public: The round part of the match number
+		#
+		# Examples
+		#
+		#   match_number = MatchNumber.new('qf1m2r3')
+		#   match_number.round
+		#   # => 2
+		attr_reader :round
+
+		# Public: The type of the match.
+		#
+		# Examples
+		#
+		#   match_number = MatchNumber.new('qf1m2r3')
+		#   match_number.type
+		#   # => :quarterfinal
+		attr_reader :type
+
+		# Public: Convert a stored match number to a MatchNumber object.
+		#
+		# object - String representation of a match number (mongoized)
+		#
+		# Returns MatchNumber parsed from object.
 		def self.demongoize(object)
 			# `object' should *always* be a string (since MatchNumber#mongoize returns a
 			# String which is what is stored in the database)
@@ -25,6 +58,15 @@ module FReCon
 			MatchNumber.new(object)
 		end
 
+		# Public: Convert a MatchNumber object to a storable string representation.
+		#
+		# object - A MatchNumber, String, or Hash. If MatchNumber, run #mongoize on
+		#          it.  If String, create a new MatchNumber object for it, then run
+		#          #mongoize on it. If Hash, convert its keys to symbols, then
+		#          pull out the :alliance and :number keys to generate a
+		#          MatchNumber.
+		#
+		# Returns String containing the mongo-ready value for the representation.
 		def self.mongoize(object)
 			case object
 			when MatchNumber
@@ -36,6 +78,16 @@ module FReCon
 			end
 		end
 
+		# Public: Convert a MatchNumber object to a storable string representation
+		# for queries.
+		#
+		# object - A MatchNumber, String, or Hash. If MatchNumber, run #mongoize on
+		#          it.  If String, create a new MatchNumber object for it, then run
+		#          #mongoize on it. If Hash, convert its keys to symbols, then
+		#          pull out the :alliance and :number keys to generate a
+		#          MatchNumber.
+		#
+		# Returns String containing the mongo-ready value for the representation.
 		def self.evolve(object)
 			case object
 			when MatchNumber
@@ -47,6 +99,9 @@ module FReCon
 			end
 		end
 
+		# Public: Convert to a storable string representation.
+		#
+		# Returns String representing the MatchNumber's data.
 		def mongoize
 			to_s
 		end
@@ -156,6 +211,9 @@ module FReCon
 			end
 		end
 
+		# Public: Convert to a String.
+		#
+		# Returns String representing the match number data.
 		def to_s
 			type_string = case @type
 			              when :practice
@@ -175,30 +233,38 @@ module FReCon
 			"#{type_string}#{@round}#{match_string}#{replay_string}"
 		end
 
+		# Public: Determine if MatchNumber represents a replay.
 		def replay?
 			!@replay_number.nil? && @replay_number > 0
 		end
 
+		# Public: Determine if MatchNumber represents a practice match.
 		def practice?
 			@type == :practice
 		end
 
+		# Public: Determine if MatchNumber represents a qualification match.
 		def qualification?
 			@type == :qualification
 		end
 
+		# Public: Determine if MatchNumber represents a quarterfinal match.
 		def quarterfinal?
 			@type == :quarterfinal
 		end
 
+		# Public: Determine if MatchNumber represents a semifinal match.
 		def semifinal?
 			@type == :semifinal
 		end
 
+		# Public: Determine if MatchNumber represents a final match.
 		def final?
 			@type == :final
 		end
 
+		# Public: Determine if MatchNumber represents a match of any elimination
+		# type.
 		def elimination?
 			ELIMINATION_TYPES.include?(@type)
 		end

data/lib/frecon/model.rb

@@ -11,46 +11,101 @@ require "mongoid"
 require "frecon/mongoid/criteria"
 
 module FReCon
+	# Public: A base class designed to assist with creating MongoDB Models
+	# elsewhere in the project.
 	class Model
+		# Public: Bootstraps inheritors of this class as working
+		# Models, also providing class methods for them to use.
+		#
+		# child - The class that is inheriting this class.
+		#
+		# Returns the result of bootstrapping the child.
 		def self.inherited(child)
 			child.class_eval do
+				# Include the various Mongoid modules that we want to use.
 				include Mongoid::Document
 				include Mongoid::Timestamps
 				include Mongoid::Attributes::Dynamic
 
+				# Ensure that no invalid relations exist.
 				validate :no_invalid_relations
 
 				self.class_variable_set(:@@attributes, [])
 
+				# Public: Register a method as a routable relation method.
+				#
+				# Models can register relation methods that they have defined
+				# (e.g. team.robots) as routable methods.  The Routes module reads
+				# these routable relations, and generates routes for them.
+				#
+				# method    - A Symbol containing the name of the relation method.
+				# attribute - A String representing the attribute that the Routes
+				#             module should route this method under.
+				#
+				# Examples
+				#
+				#   # (Taken from the Team model)
+				#   register_routable_relation :matches, "matches"
+				#
+				# Returns the result of pushing an object to class's attributes
+				#   class variable.
 				def self.register_routable_relation(method, attribute)
 					self.class_variable_get(:@@attributes) << {method: method, type: :relation, attribute: attribute}
 				end
 
+				# Public: Register a method as a routable attribute method.
+				#
+				# Models can register attribute methods that they have defined
+				# (e.g. team.number) as attribute methods.  The Routes module reads
+				# these routable attributes, and generates routes for them.
+				#
+				# method    - A Symbol containing the name of the attribute method.
+				# attribute - A String representing the attribute that the Routes
+				#             module should route this method under.
+				#
+				# Returns the result of pushing an object to class's attributes
+				#   class variable.
 				def self.register_routable_attribute(method, attribute)
 					self.class_variable_get(:@@attributes) << {method: method, type: :attribute, attribute: attribute}
 				end
 			end
 		end
 
+		# Public: Gets the descendants for the Model class.
+		#
+		# Returns all of the descendants for the Model class.
 		def self.descendants
-			# Basically lists all of the models in this database.
-			ObjectSpace.each_object(Class).select { |possibleChild| possibleChild < self }
+			ObjectSpace.each_object(Class).select { |possible_child| possible_child < self }
 		end
 
+		# Public: Converts this Model to its associated Controller.
+		#
+		# Returns the associated Controller if it exists, else nil.
 		def self.controller
 			(self.name.pluralize + "Controller").constantize
 		end
 
+		# Public: Validate that no invalid relations exist within this Model
 		def no_invalid_relations
 			# Get all of the belongs_to fields (ends with "_id" and not "_id" because that is the id).
-			attributes.keys.select { |attribute| attribute.end_with?("_id") && attribute != "_id" }.each do |relation|
+			attributes.keys.select do |attribute|
+				attribute.end_with?("_id") && attribute != "_id"
+			end.each do |relation|
 				# Get the model for the belongs_to association.
 				model = "FReCon::".concat(relation.gsub(/_id\Z/, "").capitalize).constantize
-				errors.add(relation.to_sym, "is invalid") if relation_invalid(model, send(relation))
+				errors.add(relation.to_sym, "is invalid") if relation_invalid?(model, send(relation))
 			end
 		end
 
-		def relation_invalid(class_constant, id)
+		protected
+
+		# Internal: Determine if a relation is invalid.
+		#
+		# class_constant - The Model Class to test.
+		# id             - The ID to check for extance.
+		#
+		# Returns true if the relation is invalid, false if not.
+		def relation_invalid?(class_constant, id)
 			class_constant.find_by(id: id).nil?
 		end
 	end

data/lib/frecon/models/competition.rb

@@ -10,6 +10,7 @@
 require "frecon/model"
 
 module FReCon
+	# Public: The Competition model.
 	class Competition < Model
 		field :location, type: String
 		field :name, type: String
@@ -20,14 +21,17 @@ module FReCon
 		validates :location, :name, presence: true
 		validates :name, uniqueness: true
 
+		# Public: Get this Competition's Matches' Records
 		def records
 			Record.in match_id: matches.map(&:id)
 		end
 
+		# Public: Get this Competition's Participations' Robots
 		def robots
 			Robot.in id: participations.map(&:robot_id)
 		end
 
+		# Public: Get this Competition's Participations' Robots' Teams
 		def teams
 			Team.in id: robots.map(&:team_id)
 		end

data/lib/frecon/models/match.rb

@@ -11,6 +11,7 @@ require "frecon/model"
 require "frecon/match_number"
 
 module FReCon
+	# Public: The Match model.
 	class Match < Model
 		field :number, type: MatchNumber
 
@@ -22,14 +23,17 @@ module FReCon
 
 		validates :number, :competition_id, presence: true
 
+		# Public: Get this Match's Participations
 		def participations
 			Participation.in id: records.map(&:participation_id)
 		end
 
+		# Public: Get this Match's Participations' Robots
 		def robots
 			Robot.in id: participations.map(&:robot_id)
 		end
 
+		# Public: Get this Match's Participations' Robots' Teams
 		def teams
 			Team.in id: robots.map(&:team_id)
 		end

data/lib/frecon/models/participation.rb

@@ -10,6 +10,7 @@
 require "frecon/model"
 
 module FReCon
+	# Public: The Participation model.
 	class Participation < Model
 		belongs_to :robot
 		belongs_to :competition
@@ -17,10 +18,12 @@ module FReCon
 
 		validates :robot_id, :competition_id, presence: true
 
+		# Public: Get this Participation's Robot's Team
 		def team
 			robot.team
 		end
 
+		# Public: Get this Participation's Competition's Matches
 		def matches
 			competition.matches
 		end

data/lib/frecon/models/record.rb

@@ -11,6 +11,7 @@ require "frecon/model"
 require "frecon/position"
 
 module FReCon
+	# Public: The Record model.
 	class Record < Model
 		field :notes, type: String
 		field :position, type: Position
@@ -20,14 +21,17 @@ module FReCon
 
 		validates :position, :match_id, :participation_id, presence: true
 
+		# Public: Get this Record's Match's Competition
 		def competition
 			match.competition
 		end
 
+		# Public: Get this Record's Participation's Robot
 		def robot
 			participation.robot
 		end
 
+		# Public: Get this Record's Participation's Robot's Team
 		def team
 			participation.robot.team
 		end

data/lib/frecon/models/robot.rb

@@ -10,6 +10,7 @@
 require "frecon/model"
 
 module FReCon
+	# Public: The Robot model.
 	class Robot < Model
 		# This is an optional field we included for organization.
 		field :name, type: String
@@ -19,14 +20,17 @@ module FReCon
 
 		validates :team_id, presence: true
 
+		# Public: Get this Robot's Participations' Competitions
 		def competitions
 			Competition.in id: participations.map(&:competition_id)
 		end
 
+		# Public: Get this Robot's Participations' Records
 		def records
 			Record.in participation_id: participations.map(&:id)
 		end
 
+		# Public: Get this Robot's Participations' Records' Matches
 		def matches
 			Match.in id: records.map(&:match_id).uniq
 		end

data/lib/frecon/models/team.rb

@@ -10,6 +10,7 @@
 require "frecon/model"
 
 module FReCon
+	# Public: The Team model.
 	class Team < Model
 		field :number, type: Integer
 
@@ -21,23 +22,31 @@ module FReCon
 
 		validates :number, presence: true, uniqueness: true, numericality: { greater_than: 0 }
 
+		# Public: Find a team by number.
+		#
+		# team_number - An Integer to be used to compare.
+		#
+		# Returns a Team if one exists with the given number, otherwise nil.
 		def self.number(team_number)
-			# Team.find_by number: team_number
 			find_by number: team_number
 		end
 
+		# Public: Get this Team's Robots' Participations
 		def participations
 			Participation.in robot_id: robots.map(&:id)
 		end
 
+		# Public: Get this Team's Robots' Participations' Competitions
 		def competitions
 			Competition.in id: participations.map(&:competition_id)
 		end
 
+		# Public: Get this Team's Robots' Participations' Records
 		def records
 			Record.in participation_id: participations.map(&:id)
 		end
 
+		# Public: Get this Team's Robots' Participations' Competitions' Matches
 		def matches
 			Match.in competition_id: competitions.map(&:id)
 		end

data/lib/frecon/mongoid/criteria.rb

@@ -9,24 +9,63 @@
 
 require "mongoid"
 
+# Public: An extension for the Mongoid module.
 module Mongoid
+	# Public: A monkey-patch for the Mongoid::Criteria class which introduces
+	# a #psv_filter method.
 	class Criteria
+		# Public: Filter by given PSV parameters.
+		#
+		# PSV is an introduced system that can be used within query strings to
+		# narrow a query.  Since HTTP query strings can use "+" to act as spaces
+		# within a key-value pair, one can use these pluses to define nested
+		# query parameters when querying the database as in an indexing or
+		# showing request.
+		#
+		# psv_parameters - A Hash of PSV strings to comparison values.
+		#
+		# Examples
+		#
+		#   Record.all.psv_filter({"participation robot team number" => "2503"})
+		#   => #<Mongoid::Criteria ...>
+		#
+		#   # Since each instance of Record has a :team shortcut method,
+		#   # we can just filter it like so.
+		#   Record.all.psv_filter({"team number" => "2503"})
+		#   => #<Mongoid::Criteria ...>
+		#
+		# Returns a filtered version of self.
 		def psv_filter(psv_parameters = {})
 			collection = self
 
+			# Iterate through the Hash of query Strings to values, filtering using
+			# each pairing where the key is the query specifier and the value is the
+			# value that the last word in the query specifier is equal to.  For
+			# multiple key-value pairs, just keep adding specifiers to the chain.
 			psv_parameters.each do |psv_string, comparison_value|
-				psv_keys = psv_string.split(" ").map do |psv_key|
+				# Split the query String, and convert each subsequent String
+				# to a symbol.  Then, reverse the array to make it easy to perform
+				# an inside-out operation.
+				psv_keys = psv_string.split(/\W/).map do |psv_key|
 					psv_key.to_sym
 				end.reverse
 
+				# Get the final key in the query string.
 				comparison_key = psv_keys.shift
 
+				# Create a comparison hash to be used to compare <attribute> to
+				# <expected value>.
 				if comparison_value.length == 0 || comparison_value == "__nil__"
 					comparison_hash = {comparison_key => nil}
 				else
 					comparison_hash = {comparison_key => comparison_value}
 				end
 
+				# Each of the subsequent keys should be a model name.  Generate a string
+				# corresponding to the "<model>" + "_id" for use as the comparison key,
+				# and find the model class by generating a constant.
+				#
+				# Then, nest a comparison around the current comparison hash.
 				psv_keys.each do |model|
 					model_id = (model.to_s + '_id').to_sym
 					model_class = ("FReCon::" + model.to_s.capitalize).constantize
@@ -34,9 +73,11 @@ module Mongoid
 					comparison_hash = {model_id => model_class.in(comparison_hash).map(&:id)}
 				end
 
+				# Finally, complete this nested comparison.
 				collection = collection.in(comparison_hash)
 			end
 
+			# Return the fully-filtered collection.
 			collection
 		end
 	end

data/lib/frecon/position.rb

@@ -10,20 +10,47 @@
 require "frecon/base"
 
 module FReCon
+	# Public: A wrapper to handle converting team positions and storing them.
 	class Position
-		attr_reader :alliance, :number
-
-		# MongoDB compatibility methods.
+		# Public: The alliance part of the position
+		#
+		# Examples
+		#
+		#   position = Position.new('r2')
+		#   position.alliance
+		#   # => :red
+		attr_reader :alliance
+
+		# Public: The slot part of the position.
+		#
+		# Examples
+		#
+		#   position = Position.new('r2')
+		#   position.number
+		#   # => 2
+		attr_reader :number
+
+		# Public: Convert a stored position to a Position object.
+		#
+		# object - String representation of a position (mongoized)
+		#
+		# Returns Position parsed from object.
 		def self.demongoize(object)
-			# `object' should *always* be a string (since MatchNumber#mongoize returns a
+			# `object' should *always* be a String (since MatchNumber#mongoize returns a
 			# String which is what is stored in the database)
 			raise ArgumentError, "`object' must be a String" unless object.is_a?(String)
 
 			Position.new(object)
 		end
 
-		# Allows passing a String or Hash instead of a Position.
-		# i.e. record.position = "r3"
+		# Public: Convert a Position object to a storable string representation.
+		#
+		# object - A Position, String, or Hash.  If Position, run #mongoize on it.
+		#          If String, create a new Position object for it, then run
+		#          #mongoize on it. If Hash, convert its keys to symbols, then
+		#          pull out the :alliance and :number keys to generate a Position.
+		#
+		# Returns String containing the mongo-ready value for the representation.
 		def self.mongoize(object)
 			case object
 			when Position
@@ -39,7 +66,15 @@ module FReCon
 			end
 		end
 
-		# Used for queries.
+		# Public: Convert a Position object to a storable string representation for
+		# queries.
+		#
+		# object - A Position, String, or Hash.  If Position, run #mongoize on it.
+		#          If String, create a new Position object for it, then run
+		#          #mongoize on it. If Hash, convert its keys to symbols, then
+		#          pull out the :alliance and :number keys to generate a Position.
+		#
+		# Returns String containing the mongo-ready value for the representation.
 		def self.evolve(object)
 			case object
 			when Position
@@ -55,6 +90,9 @@ module FReCon
 			end
 		end
 
+		# Public: Convert to a storable string representation.
+		#
+		# Returns String representing the Position's data.
 		def mongoize
 			to_s
 		end
@@ -112,14 +150,19 @@ module FReCon
 			end
 		end
 
+		# Public: Convert to a String.
+		#
+		# Returns String representing the position data.
 		def to_s
 			"#{@alliance[0]}#{@number}"
 		end
 
+		# Public: Determine if Position is on blue alliance.
 		def is_blue?
 			@alliance == :blue
 		end
 
+		# Public: Determine if Position is on red alliance.
 		def is_red?
 			@alliance == :red
 		end

data/lib/frecon/request_error.rb

@@ -9,9 +9,17 @@
 
 require "json"
 
+# Public: A class representing errors that emanate from request handling.
 class RequestError < StandardError
+	# Public: The Array or Integer representing what can be returned from the
+	# request handler.
 	attr_reader :return_value
 
+	# Public: Initialize a RequestError.
+	#
+	# code    - An Integer representing the HTTP status code.
+	# message - A String representing the error message.
+	# context - An Object containing any necessary debugging values.
 	def initialize(code, message = nil, context = nil)
 		@code = code
 		@message = message

data/lib/frecon/routes.rb

@@ -10,7 +10,13 @@
 require "frecon/controllers"
 
 module FReCon
+	# Public: A module containing all of the routes.
 	module Routes
+		# Public: Set up basic resource route handlers.
+		#
+		# base       - Sinatra::Application to register the routes under.
+		# name       - String containing the model name.
+		# controller - Controller-like object that contains key methods.
 		def self.resource_routes(base, name, controller)
 			base.post "/#{name}" do
 				begin
@@ -53,6 +59,11 @@ module FReCon
 			end
 		end
 
+		# Public: Set up basic attribute route handlers.
+		#
+		# base       - Sinatra::Application to register the routes under.
+		# name       - String containing the model name.
+		# controller - Controller-like object.
 		def self.attribute_routes(base, name, controller)
 			model = controller.model
 
@@ -82,6 +93,9 @@ module FReCon
 			end
 		end
 
+		# Public: Bootstrap the routes into inclusors of this module.
+		#
+		# base - The child that included this module (should be a Sinatra App)
 		def self.included(base)
 			resource_routes base, "teams", TeamsController
 			resource_routes base, "competitions", CompetitionsController

data/lib/frecon/server.rb

@@ -16,6 +16,7 @@ require "frecon/routes"
 require "frecon/controllers"
 
 module FReCon
+	# Public: The Sinatra web server.
 	class Server < Sinatra::Base
 		include Routes
 
@@ -23,23 +24,45 @@ module FReCon
 			content_type "application/json"
 		end
 
+		# Public: Start the Server.
+		#
+		# keyword_arguments - The Hash of arguments to use.
+		#                     :configuration - The Configuration to use when
+		#                                      setting up the server.
+		#
+		# Returns the result of starting the server.
 		def self.start(**keyword_arguments)
 			run!(**keyword_arguments)
 		end
 
 		protected
 
+		# Internal: Set up the server.
+		#
+		# Sets the various Thin and Sinatra options, and sets up the database.
+		#
+		# :configuration - The Configuration to use when starting the server.
+		#
+		# Returns the result of setting up the database.
 		def self.setup!(configuration: Configuration.construct!)
+			# Set the Thin and Sinatra options.
 			set :server, %w[thin HTTP webrick]
 			set :bind, configuration["frecon"]["server"]["host"]
 			set :port, configuration["frecon"]["server"]["port"]
 			set :environment, configuration["frecon"]["server"]["environment"]
 
+			# Grab out the mongoid configuration.
 			mongoid = configuration["frecon"]["database"]["mongoid"]
 
-			Database.setup(environment: environment, mongoid: mongoid)
+			# Set up the database.
+			Database.setup(environment, mongoid)
 		end
 
+		# Internal: Set up the server and start it.
+		#
+		# keyword_arguments - The Hash of arguments to use.
+		#                     :configuration - The Configuration to use when
+		#                                      setting up the server.
 		def self.run!(**keyword_arguments)
 			setup!(**keyword_arguments)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: frecon
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Sam Craig
@@ -71,6 +71,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: yard-tomdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: yard-mongoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
 description: A JSON API for scouting FRC competitions that manages the database for
   the user.
 email: frc-frecon@googlegroups.com
@@ -79,6 +121,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- Gemfile
+- Rakefile
 - bin/frecon
 - config/default.yml
 - lib/frecon.rb