icu_tournament 1.1.2 → 1.2.0

data/lib/icu_tournament/result.rb

@@ -1,91 +1,84 @@
 # encoding: utf-8
 
 module ICU
-
-=begin rdoc
-
-== Result
-
-A result is the outcome of a game from the perspective of one of the players.
-If the game was not a bye or a walkover and involved a second player, then
-that second player will also have a result for the same game, and the two
-results will be mirror images of each other.
-
-A result always involves a round number, a player number and a score, so these
-three attributes must be supplied in the constructor.
-
-  result = ICU::Result.new(2, 10, 'W')
-
-The above example represents player 10 winning in round 2. As it stands, it represends
-a bye or walkover since there is no opponent. Without an opponent, it is unrateable.
-
-  result.rateable     # => false
-
-The player's colour and the number of their opponent can be set as follows:
-
-  result.colour = 'B'
-  result.opponent = 13
-
-Specifying an opponent always makes a result rateable.
-
-  result.rateable     # => true
-
-This example now represents a win by player 10 with the black pieces over player number 13 in round 2.
-Alternatively, all this can been specified in the constructor.
-
-  result = ICU::Result.new(2, 10, 'W', :opponent => 13, :colour => 'B')
-
-To make a game unratable, even if it involves an opponent, set the _rateable_ atribute explicity:
-
-  result.rateable = false
-
-or include it in the constructor:
-
-  result = ICU::Result.new(2, 10, 'W', :opponent => 13, :colour => 'B', :rateable => false)
-
-The result of the same game from the perspective of the opponent is:
-
-  tluser = result.reverse
-
-which, with the above example, would be:
-
-  tluser.player       # => 13
-  tluser.opponent     # => 10
-  tluser.score        # => 'L'
-  tluser.colour       # => 'B'
-  tluser.round        # => 2
-
-The reversed result copies the _rateable_ attribute of the original unless an
-explicit override is supplied.
-
-  result.rateable                 # => true
-  result.reverse.rateable         # => true (copied from original)
-  result.reverse(false).rateable  # => false (overriden)
-
-A result which has no opponent is not reversible (the _reverse_ method returns _nil_).
-
-The return value from the _score_ method is always one of _W_, _L_ or _D_. However,
-when setting the score, a certain amount of variation is permitted as long as it is
-clear what is meant. For eample, the following would all be converted to _D_:
-
-  result.score = ' D '
-  result.score = 'd'
-  result.score = '='
-  result.score = '0.5'
-  result.score = '½'
-
-The _points_ read-only accessor always returns a floating point number: either 0.0, 0.5 or 1.0.
-
-=end
-
+  #
+  # A result is the outcome of a game from the perspective of one of the players.
+  # If the game was not a bye or a walkover and involved a second player, then
+  # that second player will also have a result for the same game, and the two
+  # results will be mirror images of each other.
+  #
+  # A result always involves a round number, a player number and a score, so these
+  # three attributes must be supplied in the constructor.
+  #
+  #   result = ICU::Result.new(2, 10, 'W')
+  #
+  # The above example represents player 10 winning in round 2. As it stands, it represends
+  # a bye or walkover since there is no opponent. Without an opponent, it is unrateable.
+  #
+  #   result.rateable     # => false
+  #
+  # The player's colour and the number of their opponent can be set as follows:
+  #
+  #   result.colour = 'B'
+  #   result.opponent = 13
+  #
+  # Specifying an opponent always makes a result rateable.
+  #
+  #   result.rateable     # => true
+  #
+  # This example now represents a win by player 10 with the black pieces over player number 13 in round 2.
+  # Alternatively, all this can been specified in the constructor.
+  #
+  #   result = ICU::Result.new(2, 10, 'W', :opponent => 13, :colour => 'B')
+  #
+  # To make a game unratable, even if it involves an opponent, set the _rateable_ atribute explicity:
+  #
+  #   result.rateable = false
+  #
+  # or include it in the constructor:
+  #
+  #   result = ICU::Result.new(2, 10, 'W', :opponent => 13, :colour => 'B', :rateable => false)
+  #
+  # The result of the same game from the perspective of the opponent is:
+  #
+  #   tluser = result.reverse
+  #
+  # which, with the above example, would be:
+  #
+  #   tluser.player       # => 13
+  #   tluser.opponent     # => 10
+  #   tluser.score        # => 'L'
+  #   tluser.colour       # => 'B'
+  #   tluser.round        # => 2
+  #
+  # The reversed result copies the _rateable_ attribute of the original unless an
+  # explicit override is supplied.
+  #
+  #   result.rateable                 # => true
+  #   result.reverse.rateable         # => true (copied from original)
+  #   result.reverse(false).rateable  # => false (overriden)
+  #
+  # A result which has no opponent is not reversible (the _reverse_ method returns _nil_).
+  #
+  # The return value from the _score_ method is always one of _W_, _L_ or _D_. However,
+  # when setting the score, a certain amount of variation is permitted as long as it is
+  # clear what is meant. For eample, the following would all be converted to _D_:
+  #
+  #   result.score = ' D '
+  #   result.score = 'd'
+  #   result.score = '='
+  #   result.score = '0.5'
+  #   result.score = '½'
+  #
+  # The _points_ read-only accessor always returns a floating point number: either 0.0, 0.5 or 1.0.
+  #
   class Result
-    
     extend ICU::Accessor
     attr_positive :round
     attr_integer :player
-    
+
     attr_reader :score, :colour, :opponent, :rateable
-    
+
     # Constructor. Round number, player number and score must be supplied.
     # Optional hash attribute are _opponent_, _colour_ and _rateable_.
     def initialize(round, player, score, opt={})
@@ -95,7 +88,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
       [:colour, :opponent].each { |a| self.send("#{a}=", opt[a]) unless opt[a].nil? }
       self.rateable = opt[:rateable]  # always attempt to set this, and do it last, to get the right default
     end
-    
+
     # Score for the game, even if a default. One of 'W', 'L' or 'D'. Reasonable inputs like 1, 0, =, ½, etc will be converted.
     def score=(score)
       @score = case score.to_s.strip
@@ -105,7 +98,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
         else raise "invalid score (#{score})"
       end
     end
-    
+
     # Return the score as a floating point number.
     def points
       case @score
@@ -114,7 +107,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
         else 0.5
       end
     end
-    
+
     # Colour. Either 'W' (white) or 'B' (black).
     def colour=(colour)
       @colour = case colour.to_s
@@ -124,7 +117,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
         else raise "invalid colour (#{colour})"
       end
     end
-    
+
     # Opponent player number. Either absent (_nil_) or any integer except the player number.
     def opponent=(opponent)
       @opponent = case opponent
@@ -137,7 +130,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
       raise "opponent number and player number (#{@opponent}) must be different" if @opponent == player
       self.rateable = true if @opponent
     end
-    
+
     # Rateable flag. If false, result is not rateable. Can only be true if there is an opponent.
     def rateable=(rateable)
       if opponent.nil?
@@ -150,7 +143,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
         else true
       end
     end
-    
+
     # Return a reversed version (from the opponent's perspective) of a result.
     def reverse(rateable=nil)
       return unless @opponent
@@ -161,7 +154,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
       r.rateable = rateable || @rateable
       r
     end
-    
+
     # Renumber the player and opponent (if there is one) according to the supplied hash. Return self.
     def renumber(map)
       raise "result player number #{@player} not found in renumbering hash" unless map[@player]
@@ -174,7 +167,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
       end
       self
     end
-    
+
     # Loose equality. True if the round, player and opponent numbers, colour and score all match.
     def ==(other)
       return unless other.is_a? Result
@@ -183,7 +176,7 @@ The _points_ read-only accessor always returns a floating point number: either 0
       end
       true
     end
-    
+
     # Strict equality. True if the there's loose equality and also the rateablity is the same.
     def eql?(other)
       return true if equal?(other)

data/lib/icu_tournament/team.rb

@@ -1,65 +1,58 @@
 module ICU
-
-=begin rdoc
-
-== Team
-
-A team consists of a name and one or more players referenced by numbers.
-Typically the team will be attached to a tournament (ICU::Tournament)
-and the numbers will the unique numbers by which the players in that
-tournament are referenced. To instantiate a team, you must supply a
-name.
-
-  team = ICU::Team.new('Wandering Dragons')
-
-Then you simply add player's (numbers) to it.
-
-  team.add_player(1)
-  team.add_payeer(3)
-  team.add_player(7)
-
-To get the current members of a team
-
-  team.members                                 # => [1, 3, 7]
-
-You can enquire whether a team contains a given player number.
-
-  team.contains?(3)                            # => true
-  team.contains?(4)                            # => false
-
-Or whether it matches a given name (which ignoring case and removing spurious whitespace)
-  
-  team.matches(' wandering  dragons  ')        # => true
-  team.matches('Blundering Bishops')           # => false
-
-Whenever you reset the name of a tournament spurious whitespace is removed but case is not altered.
-
-  team.name = '  blundering  bishops  '
-  team.name                                    # => "blundering bishops"
-
-Attempting to add non-numbers or duplicate numbers as new team members results in an exception.
-
-  team.add(nil)                                # exception - not a number
-  team.add(3)                                  # exception - already a member
-
-=end
-
+  #
+  # A team consists of a name and one or more players referenced by numbers.
+  # Typically the team will be attached to a tournament (ICU::Tournament)
+  # and the numbers will the unique numbers by which the players in that
+  # tournament are referenced. To instantiate a team, you must supply a
+  # name.
+  #
+  #   team = ICU::Team.new('Wandering Dragons')
+  #
+  # Then you simply add player's (numbers) to it.
+  #
+  #   team.add_player(1)
+  #   team.add_payeer(3)
+  #   team.add_player(7)
+  #
+  # To get the current members of a team
+  #
+  #   team.members                                 # => [1, 3, 7]
+  #
+  # You can enquire whether a team contains a given player number.
+  #
+  #   team.contains?(3)                            # => true
+  #   team.contains?(4)                            # => false
+  #
+  # Or whether it matches a given name (which ignoring case and removing spurious whitespace)
+  #
+  #   team.matches(' wandering  dragons  ')        # => true
+  #   team.matches('Blundering Bishops')           # => false
+  #
+  # Whenever you reset the name of a tournament spurious whitespace is removed but case is not altered.
+  #
+  #   team.name = '  blundering  bishops  '
+  #   team.name                                    # => "blundering bishops"
+  #
+  # Attempting to add non-numbers or duplicate numbers as new team members results in an exception.
+  #
+  #   team.add(nil)                                # exception - not a number
+  #   team.add(3)                                  # exception - already a member
+  #
   class Team
-
     attr_reader :name, :members
-    
+
     # Constructor. Name must be supplied.
     def initialize(name)
       self.name = name
       @members = Array.new
     end
-    
+
     # Set name. Must not be blank.
     def name=(name)
       @name = name.strip.squeeze(' ')
       raise "team can't be blank" if @name.length == 0
     end
-    
+
     # Add a team member referenced by any integer.
     def add_member(number)
       pnum = number.to_i
@@ -67,7 +60,7 @@ Attempting to add non-numbers or duplicate numbers as new team members results i
       raise "can't add duplicate player number #{pnum} to team '#{@name}'" if @members.include?(pnum)
       @members.push(pnum)
     end
-    
+
     # Renumber the players according to the supplied hash. Return self.
     def renumber(map)
       @members.each_with_index do |pnum, index|
@@ -76,12 +69,12 @@ Attempting to add non-numbers or duplicate numbers as new team members results i
       end
       self
     end
-    
+
     # Detect if a member exists in a team.
     def include?(number)
       @members.include?(number)
     end
-    
+
     # Does the team name match the given string (ignoring case and spurious whitespace).
     def matches(name)
       self.name.downcase == name.strip.squeeze(' ').downcase

data/lib/icu_tournament/tournament.rb

@@ -1,167 +1,157 @@
 module ICU
-
-=begin rdoc
-
-== Building a Tournament
-
-One way to create a tournament object is by parsing one of the supported file types (e.g. ICU::Tournament::Krause).
-It is also possible to build one programmatically by:
-
-1. creating a bare tournament instance,
-2. adding all the players,
-3. adding all the results.
-
-For example:
-
-  require 'rubygems'
-  require 'icu_tournament'
-
-  t = ICU::Tournament.new('Bangor Masters', '2009-11-09')
-
-  t.add_player(ICU::Player.new('Bobby', 'Fischer', 10))
-  t.add_player(ICU::Player.new('Garry', 'Kasparov', 20))
-  t.add_player(ICU::Player.new('Mark', 'Orr', 30))
-
-  t.add_result(ICU::Result.new(1, 10, 'D', :opponent => 30, :colour => 'W'))
-  t.add_result(ICU::Result.new(2, 20, 'W', :opponent => 30, :colour => 'B'))
-  t.add_result(ICU::Result.new(3, 20, 'L', :opponent => 10, :colour => 'W'))
-
-  t.validate!(:rerank => true)
-
-and then:
-
-  serializer = ICU::Tournament::Krause.new
-  puts serializer.serialize(@t)
-
-or equivalntly, just:
-
-  puts t.serialize('Krause')
-
-would result in the following output:
-
-  012 Bangor Masters
-  042 2009-11-09
-  001   10      Fischer,Bobby                                                      1.5    1    30 w =              20 b 1
-  001   20      Kasparov,Garry                                                     1.0    2              30 b 1    10 w 0
-  001   30      Orr,Mark                                                           0.5    3    10 b =    20 w 0
-
-Note that the players should be added first because the _add_result_ method will
-raise an exception if the players it references through their tournament numbers
-(10, 20 and 30 in this example) have not already been added to the tournament.
-
-See ICU::Player and ICU::Result for more details about players and results.
-
-
-== Validation
-
-A tournament can be validated with either the <em>validate!</em> or _invalid_ methods.
-On success, the first returns true while the second returns false.
-On error, the first throws an exception while the second returns a string
-describing the error.
-
-Validations checks that:
-
-* there are at least two players
-* every player has a least one result
-* the result round numbers are consistent (no more than one game per player per round)
-* the tournament dates (start, finish, round dates), if there are any, are consistent
-* the player ranks are consistent with their scores
-
-Side effects of calling <em>validate!</em> or _invalid_ include:
-
-* the number of rounds will be set if not set already
-* the finish date will be set if not set already and if there are round dates
-
-Optionally, additional validation checks can be performed given a tournament
-parser/serializer. For example:
-
-  t.validate!(:type => ICU::Tournament.ForeignCSV.new)
-
-Or equivalently:
-
-  t.validate!(:type => 'ForeignCSV')
-
-Such additional validation is always performed before a tournament is serialized.
-For example, the following are equivalent and will throw an exception if
-the tournament is invalid according to either the general rules or the rules
-specific for the type used:
-
-  t.serialize('ForeignCSV')
-  ICU::Tournament::ForeignCSV.new.serialize(t)
-
-== Ranking
-
-The players in a tournament can be ranked by calling the _rerank_ method directly.
-
-  t.rerank
-
-Alternatively they can be ranked as a side effect of validation if the _rerank_ option is set,
-but this only applies if the tournament is not yet ranked or it's ranking is inconsistent.
-
-  t.validate(:rerank => true)
-
-Ranking is inconsistent if some but not all players have a rank or if all players
-have a rank but some are ranked higher than others on lower scores.
-
-To rank the players requires a tie break method to be specified to order players on the same score.
-The default is alphabetical (by last name then first name). Other methods can be specified by supplying
-an array of methods (strings or symbols) in order of precedence to the _tie_breaks_ setter. Examples:
-
-  t.tie_breaks = ['Sonneborn-Berger']
-  t.tie_breaks = [:buchholz, :neustadtl, :blacks, :wins]
-  t.tie_breaks = []  # reset to the default
-
-The full list of supported methods is:
-
-* _Buchholz_: sum of opponents' scores
-* _Harkness_ (or _median_): like Buchholz except the highest and lowest opponents' scores are discarded (or two highest and lowest if 9 rounds or more)
-* _modified_median_: same as Harkness except only lowest (or highest) score(s) are discarded for players with more (or less) than 50%
-* _Neustadtl_ (or _Sonneborn-Berger_): sum of scores of players defeated plus half sum of scores of players drawn against
-* _progressive_ (or _cumulative_): sum of running score for each round
-* _ratings_: sum of opponents ratings
-* _blacks_: number of blacks
-* _wins_: number of wins
-* _name_: alphabetical by name (if _tie_breaks_ is set to an empty array, as it is initially, then this will be used as the back-up tie breaker)
-
-The return value from _rerank_ is the tournament object itself, to allow chaining, for example:
-
-  t.rerank.renumber
-
-
-== Renumbering
-
-The numbers used to uniquely identify each player in a tournament can be any set of unique integers
-(including zero and negative numbers). To renumber the players so that these numbers start at 1 and
-end with the total number of players, use the _renumber_ method. This method takes one optional
-argument to specify how the renumbering is done.
-
-  t.renumber(:rank)       # renumber by rank (if there are consistent rankings), otherwise by name alphabetically
-  t.renumber              # the same, as renumbering by rank is the default
-  t.renumber(:name)       # renumber by name alphabetically
-  t.renumber(:order)      # renumber maintaining the order of the original numbers
-
-The return value from _renumber_ is the tournament object itself.
-
-
-== Parsing Files
-
-As an alternative to processing files by first instantiating a parser of the appropropriate class
-(such as ICU::Tournament::SwissPerfect, ICU::Tournament::Krause and ICU::Tournament::ForeignCSV)
-and then calling the parser's <em>parse_file</em> or <em>parse_file!</em> instance method,
-a convenience class method, <em>parse_file!</em>, is available when a parser instance is not required.
-For example:
-
-  t = ICU::Tournament.parse_file!('champs.zip', 'SwissPerfect', :start => '2010-07-03')
-
-The method takes a filename, format and an options hash as arguments. It either returns
-an instance of ICU::Tournament or throws an exception. See the documentation for the
-different formats for what options are available. For some, no options are available,
-in which case any options supplied to this method will be silently ignored.
-
-=end
-
+  #
+  # One way to create a tournament object is by parsing one of the supported file types (e.g. ICU::Tournament::Krause).
+  # It is also possible to build one programmatically by:
+  #
+  # * creating a bare tournament instance,
+  # * adding all the players,
+  # * adding all the results.
+  #
+  # For example:
+  #
+  #   require 'rubygems'
+  #   require 'icu_tournament'
+  #
+  #   t = ICU::Tournament.new('Bangor Masters', '2009-11-09')
+  #
+  #   t.add_player(ICU::Player.new('Bobby', 'Fischer', 10))
+  #   t.add_player(ICU::Player.new('Garry', 'Kasparov', 20))
+  #   t.add_player(ICU::Player.new('Mark', 'Orr', 30))
+  #
+  #   t.add_result(ICU::Result.new(1, 10, 'D', :opponent => 30, :colour => 'W'))
+  #   t.add_result(ICU::Result.new(2, 20, 'W', :opponent => 30, :colour => 'B'))
+  #   t.add_result(ICU::Result.new(3, 20, 'L', :opponent => 10, :colour => 'W'))
+  #
+  #   t.validate!(:rerank => true)
+  #
+  # and then:
+  #
+  #   serializer = ICU::Tournament::Krause.new
+  #   puts serializer.serialize(@t)
+  #
+  # or equivalntly, just:
+  #
+  #   puts t.serialize('Krause')
+  #
+  # would result in the following output:
+  #
+  #   012 Bangor Masters
+  #   042 2009-11-09
+  #   001   10      Fischer,Bobby                                                      1.5    1    30 w =              20 b 1
+  #   001   20      Kasparov,Garry                                                     1.0    2              30 b 1    10 w 0
+  #   001   30      Orr,Mark                                                           0.5    3    10 b =    20 w 0
+  #
+  # Note that the players should be added first because the _add_result_ method will
+  # raise an exception if the players it references through their tournament numbers
+  # (10, 20 and 30 in this example) have not already been added to the tournament.
+  #
+  # See ICU::Player and ICU::Result for more details about players and results.
+  #
+  # == Validation
+  #
+  # A tournament can be validated with either the <em>validate!</em> or _invalid_ methods.
+  # On success, the first returns true while the second returns false.
+  # On error, the first throws an exception while the second returns a string
+  # describing the error.
+  #
+  # Validations checks that:
+  #
+  # * there are at least two players
+  # * every player has a least one result
+  # * the result round numbers are consistent (no more than one game per player per round)
+  # * the tournament dates (start, finish, round dates), if there are any, are consistent
+  # * the player ranks are consistent with their scores
+  #
+  # Side effects of calling <em>validate!</em> or _invalid_ include:
+  #
+  # * the number of rounds will be set if not set already
+  # * the finish date will be set if not set already and if there are round dates
+  #
+  # Optionally, additional validation checks can be performed given a tournament
+  # parser/serializer. For example:
+  #
+  #   t.validate!(:type => ICU::Tournament.ForeignCSV.new)
+  #
+  # Or equivalently:
+  #
+  #   t.validate!(:type => 'ForeignCSV')
+  #
+  # Such additional validation is always performed before a tournament is serialized.
+  # For example, the following are equivalent and will throw an exception if
+  # the tournament is invalid according to either the general rules or the rules
+  # specific for the type used:
+  #
+  #   t.serialize('ForeignCSV')
+  #   ICU::Tournament::ForeignCSV.new.serialize(t)
+  #
+  # == Ranking
+  #
+  # The players in a tournament can be ranked by calling the _rerank_ method directly.
+  #
+  #   t.rerank
+  #
+  # Alternatively they can be ranked as a side effect of validation if the _rerank_ option is set,
+  # but this only applies if the tournament is not yet ranked or it's ranking is inconsistent.
+  #
+  #   t.validate(:rerank => true)
+  #
+  # Ranking is inconsistent if some but not all players have a rank or if all players
+  # have a rank but some are ranked higher than others on lower scores.
+  #
+  # To rank the players requires a tie break method to be specified to order players on the same score.
+  # The default is alphabetical (by last name then first name). Other methods can be specified by supplying
+  # an array of methods (strings or symbols) in order of precedence to the _tie_breaks_ setter. Examples:
+  #
+  #   t.tie_breaks = ['Sonneborn-Berger']
+  #   t.tie_breaks = [:buchholz, :neustadtl, :blacks, :wins]
+  #   t.tie_breaks = []  # reset to the default
+  #
+  # The full list of supported methods is:
+  #
+  # * _Buchholz_: sum of opponents' scores
+  # * _Harkness_ (or _median_): like Buchholz except the highest and lowest opponents' scores are discarded (or two highest and lowest if 9 rounds or more)
+  # * _modified_median_: same as Harkness except only lowest (or highest) score(s) are discarded for players with more (or less) than 50%
+  # * _Neustadtl_ (or _Sonneborn-Berger_): sum of scores of players defeated plus half sum of scores of players drawn against
+  # * _progressive_ (or _cumulative_): sum of running score for each round
+  # * _ratings_: sum of opponents ratings
+  # * _blacks_: number of blacks
+  # * _wins_: number of wins
+  # * _name_: alphabetical by name (if _tie_breaks_ is set to an empty array, as it is initially, then this will be used as the back-up tie breaker)
+  #
+  # The return value from _rerank_ is the tournament object itself, to allow chaining, for example:
+  #
+  #   t.rerank.renumber
+  #
+  # == Renumbering
+  #
+  # The numbers used to uniquely identify each player in a tournament can be any set of unique integers
+  # (including zero and negative numbers). To renumber the players so that these numbers start at 1 and
+  # end with the total number of players, use the _renumber_ method. This method takes one optional
+  # argument to specify how the renumbering is done.
+  #
+  #   t.renumber(:rank)       # renumber by rank (if there are consistent rankings), otherwise by name alphabetically
+  #   t.renumber              # the same, as renumbering by rank is the default
+  #   t.renumber(:name)       # renumber by name alphabetically
+  #   t.renumber(:order)      # renumber maintaining the order of the original numbers
+  #
+  # The return value from _renumber_ is the tournament object itself.
+  #
+  # == Parsing Files
+  #
+  # As an alternative to processing files by first instantiating a parser of the appropropriate class
+  # (such as ICU::Tournament::SwissPerfect, ICU::Tournament::Krause and ICU::Tournament::ForeignCSV)
+  # and then calling the parser's <em>parse_file</em> or <em>parse_file!</em> instance method,
+  # a convenience class method, <em>parse_file!</em>, is available when a parser instance is not required.
+  # For example:
+  #
+  #   t = ICU::Tournament.parse_file!('champs.zip', 'SwissPerfect', :start => '2010-07-03')
+  #
+  # The method takes a filename, format and an options hash as arguments. It either returns
+  # an instance of ICU::Tournament or throws an exception. See the documentation for the
+  # different formats for what options are available. For some, no options are available,
+  # in which case any options supplied to this method will be silently ignored.
+  #
   class Tournament
-
     extend ICU::Accessor
     attr_date :start
     attr_date_or_nil :finish
@@ -389,7 +379,7 @@ in which case any options supplied to this method will be silently ignored.
       check_type(options[:type]) if options[:type]
       true
     end
-    
+
     # Convenience method to parse a file.
     def self.parse_file!(file, format, opts={})
       type = format.to_s