Fix rubydoc generation for the selectricity service.

[selectricity-live] / app / apis / selectricity_api.rb

diff --git a/app/apis/selectricity_api.rb b/app/apis/selectricity_api.rb
index 9c95369d9a798917ee68babb9d2f578c0a6b3b04..4c604755a4dce0a779769233dd91fcbe47e5a400 100644 (file)
--- a/app/apis/selectricity_api.rb
+++ b/app/apis/selectricity_api.rb
@@ -1,11 +1,11 @@
-class ElectionStruct < ActionWebService::Struct
+class QuickVoteStruct < ActionWebService::Struct

   member :name, :string
   member :description, :string
   member :candidate_ids, [:int]
   member :candidate_names, [:string]
   member :id, :int
 end
   member :name, :string
   member :description, :string
   member :candidate_ids, [:int]
   member :candidate_names, [:string]
   member :id, :int
 end

-class VoteInfo < ActionWebService::Struct
+class QuickVoterInfo < ActionWebService::Struct

   member :voter_id, :int
   member :voter_session_id, :string
   member :voter_ipaddress, :string
   member :voter_id, :int
   member :voter_session_id, :string
   member :voter_ipaddress, :string


@@ -13,26 +13,51 @@ class VoteInfo < ActionWebService::Struct
   member :vote, [:int]
 end
 
   member :vote, [:int]
 end
 

-class VoteResultStruct < ActionWebService::Struct
+class QuickVoteResultStruct < ActionWebService::Struct

   member :plurality_winners, [:int]
   member :approval_winners, [:int]
   member :condorcet_winners, [:int]
   member :ssd_winners, [:int]
   member :borda_winners, [:int]
 end
   member :plurality_winners, [:int]
   member :approval_winners, [:int]
   member :condorcet_winners, [:int]
   member :ssd_winners, [:int]
   member :borda_winners, [:int]
 end

-class CandidateMap < ActionWebService::Struct
+class QuickVoteCandidateMap < ActionWebService::Struct

   member :candidate_ids, [:int]
   member :candidate_names, [:string]
 end
   member :candidate_ids, [:int]
   member :candidate_names, [:string]
 end

+
+
+## An API for interfacing with Selectricity
+## This allows for things like XML-RPC to have a unified interface
+## The implementation is elsewhere.

 class SelectricityAPI < ActionWebService::API::Base
 class SelectricityAPI < ActionWebService::API::Base

+  ## 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.

   api_method :cast_quickvote, :expects => [:string, :int, [[:int]]], :returns => [:string]
   api_method :cast_quickvote, :expects => [:string, :int, [[:int]]], :returns => [:string]

-  api_method :get_quickvote_results, :expects => [:string], :returns => [VoteResultStruct]
-  api_method :get_quickvote_candidate_map, :expects => [:string], :returns => [CandidateMap]
+  ## Return the results of a QuickVote.
+  ## Takes in the name of a quickvote, and returns a structure as described by
+  ## QuickVoteResultStruct
+  api_method :get_quickvote_results, :expects => [:string], :returns => [QuickVoteResultStruct]
+  ## 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.
+  api_method :get_quickvote_candidate_map, :expects => [:string], :returns => [QuickVoteCandidateMap]
+  ## 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.

   api_method :quickvote_candidate_ids_to_names, :expects => [:string,[:int]], :returns => [[:string]]
   api_method :quickvote_candidate_ids_to_names, :expects => [:string,[:int]], :returns => [[:string]]

-  api_method :get_quickvote_votes, :expects => [:string], :returns => [ [VoteInfo] ]
-  api_method :list_quickvotes, :expects => [], :returns => [[ElectionStruct]]
-  api_method :get_quickvote, :expects => [:string], :returns => [ElectionStruct]
-  api_method :create_quickvote, :expects => [ElectionStruct], :returns => [:string]
+  ## Get information on all the votes cast in a QuickVote
+  ## Takes in the name of a QuickVote, returns an array of QuickVoterInfo structures.
+  api_method :get_quickvote_votes, :expects => [:string], :returns => [ [QuickVoterInfo] ]
+  ## Gets a list of all QuickVotes in the system.
+  api_method :list_quickvotes, :expects => [], :returns => [[QuickVoteStruct]]
+  ## Gets information on a particular QuickVote
+  ## Takes in a QuickVote name
+  api_method :get_quickvote, :expects => [:string], :returns => [QuickVoteStruct]
+  ## Create a QuickVote
+  ## Pass in a QuickVoteStruct populated with all the fields but the candidate ID's
+  api_method :create_quickvote, :expects => [QuickVoteStruct], :returns => [:string]

 end
 end

-
-