added quick documentation about XML-RPC interface

[selectricity-live] / app / models / selectricity_service.rb

diff --git a/app/models/selectricity_service.rb b/app/models/selectricity_service.rb
index 544b618d7c78fddce9fb5d91f8a3a65cf263264c..f5e7457ef68af24e3bb0e34de64505100e867e24 100644 (file)
--- a/app/models/selectricity_service.rb
+++ b/app/models/selectricity_service.rb
@@ -2,6 +2,10 @@ require 'action_controller/integration'
 
 class SelectricityService < ActionWebService::Base
   web_service_api SelectricityAPI
 
 class SelectricityService < ActionWebService::Base
   web_service_api SelectricityAPI

+
+  ## Casts a quickvote.
+  ## Expects a quickvote name, a voter ID, and a list of candidate ID's respectively.
+  ## Returns a string containing any potential errors that occurred in the process.

   def cast_quickvote(election_name, voter_id, vote_list)
     election = QuickVote.ident_to_quickvote election_name
     if election
   def cast_quickvote(election_name, voter_id, vote_list)
     election = QuickVote.ident_to_quickvote election_name
     if election


@@ -25,6 +29,11 @@ class SelectricityService < ActionWebService::Base
       raise ArgumentError.new("Cannot find election #{election_name}")
     end
   end
       raise ArgumentError.new("Cannot find election #{election_name}")
     end
   end

+
+  ## Converts QuickVote candidate ID's to names
+  ## Takes in a QuickVote name and a list of candidate ID's, and returns the names of
+  ## each candidate. Useful for doing just a few lookups; it's more efficient to use
+  ## get_quickvote_candidate_map for presenting info about an entire election.

   def quickvote_candidate_ids_to_names(shortname, id_list)
     qv=QuickVote.ident_to_quickvote(shortname)
     candidates={}
   def quickvote_candidate_ids_to_names(shortname, id_list)
     qv=QuickVote.ident_to_quickvote(shortname)
     candidates={}


@@ -42,10 +51,14 @@ class SelectricityService < ActionWebService::Base
     }
     results
   end
     }
     results
   end

+
+  ## Return the results of a QuickVote.
+  ## Takes in the name of a quickvote, and returns a structure as described by
+  ## QuickVoteResultStruct

   def get_quickvote_results(shortname)
     #TODO: Validate shortname
     qv=QuickVote.ident_to_quickvote(shortname)
   def get_quickvote_results(shortname)
     #TODO: Validate shortname
     qv=QuickVote.ident_to_quickvote(shortname)

-    result=VoteResultStruct.new
+    result=QuickVoteResultStruct.new

     unless qv
       raise ArgumentError.new("No quickvote with name #{shortname} found!")
     end
     unless qv
       raise ArgumentError.new("No quickvote with name #{shortname} found!")
     end


@@ -57,9 +70,15 @@ class SelectricityService < ActionWebService::Base
     result.borda_winners=qv.borda_result.winners
     result
   end
     result.borda_winners=qv.borda_result.winners
     result
   end

+
+  ## Returns information regarding all the candidates in a QuickVote
+  ## Takes in a QuickVote name, and returns the list of names and ID's of candidates
+  ## This can be useful for presenting the user with a list of readable names, while
+  ## the software sends results to us in the numeric ID's we require. The two lists are in
+  ## respective order.

   def get_quickvote_candidate_map(shortname)
     qv=QuickVote.ident_to_quickvote(shortname)
   def get_quickvote_candidate_map(shortname)
     qv=QuickVote.ident_to_quickvote(shortname)

-    result=CandidateMap.new
+    result=QuickVoteCandidateMap.new

     unless qv
       raise ArgumentError.new("No quickvote with name #{shortname} found!")
     end
     unless qv
       raise ArgumentError.new("No quickvote with name #{shortname} found!")
     end


@@ -70,6 +89,8 @@ class SelectricityService < ActionWebService::Base
     result
   end
 
     result
   end
 

+  ## Get information on all the votes cast in a QuickVote
+  ## Takes in the name of a QuickVote, returns an array of QuickVoterInfo structures.

   def get_quickvote_votes(shortname)
     qv = QuickVote.ident_to_quickvote(shortname)
 
   def get_quickvote_votes(shortname)
     qv = QuickVote.ident_to_quickvote(shortname)
 


@@ -78,7 +99,7 @@ class SelectricityService < ActionWebService::Base
     end
 
     qv.votes.collect do |vote|
     end
 
     qv.votes.collect do |vote|

-       VoteInfo.new(:voter_id => vote.voter.id,
+       QuickVoterInfo.new(:voter_id => vote.voter.id,

                     :voter_ipaddress => vote.voter.ipaddress,
                     :vote_time => vote.time.to_i,
                     :vote => vote.votes,
                     :voter_ipaddress => vote.voter.ipaddress,
                     :vote_time => vote.time.to_i,
                     :vote => vote.votes,


@@ -86,18 +107,21 @@ class SelectricityService < ActionWebService::Base
     end
   end
 
     end
   end
 

+  ## Gets a list of all QuickVotes in the system.

   def list_quickvotes()
     QuickVote.find(:all).collect do |election|
       get_quickvote(election.name)
     end
   end
 
   def list_quickvotes()
     QuickVote.find(:all).collect do |election|
       get_quickvote(election.name)
     end
   end
 

+  ## Gets information on a particular QuickVote
+  ## Takes in a QuickVote name

   def get_quickvote(shortname)
     unless election = QuickVote.ident_to_quickvote(shortname)
       raise ArgumentError.new("Cannot find QuickVote named #{shortname}")
     end
 
   def get_quickvote(shortname)
     unless election = QuickVote.ident_to_quickvote(shortname)
       raise ArgumentError.new("Cannot find QuickVote named #{shortname}")
     end
 

-    ElectionStruct.new(
+    QuickVoteStruct.new(

       :id => election.id,
       :name => election.name,
       :description => election.description,
       :id => election.id,
       :name => election.name,
       :description => election.description,


@@ -105,6 +129,9 @@ class SelectricityService < ActionWebService::Base
       :candidate_names => election.candidates.collect {|c| c.name } )
   end
 
       :candidate_names => election.candidates.collect {|c| c.name } )
   end
 

+  ## Create a QuickVote
+  ## Pass in a QuickVoteStruct populated with all the fields but the candidate ID's
+  ## Any candidate ID's you fill in will be ignored anyway.

   def create_quickvote(election)
     qv = QuickVote.new(:name => election.name,
                        :description => election.description)
   def create_quickvote(election)
     qv = QuickVote.new(:name => election.name,
                        :description => election.description)