steam-condenser 0.14.0 → 1.0.1

data/lib/steam/community/alien_swarm/alien_swarm_weapon.rb

@@ -1,20 +1,41 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2010, Sebastian Staudt
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 require 'steam/community/game_weapon'
 
-# AlienSwarmWeapon holds statistical information about weapons used by a player
-# in Alien Swarm.
+# This class holds statistical information about weapons used by a player
+# in Alien Swarm
+#
+# @author Sebastian Staudt
 class AlienSwarmWeapon
 
   include GameWeapon
 
-  attr_reader :accuracy, :damage, :friendly_fire, :name, :shots
+  # Returns the accuracy of the player with this weapon
+  #
+  # @return [Float] The accuracy of the player with this weapon
+  attr_reader :accuracy
+
+  # Returns the damage achieved with this weapon
+  #
+  # @return [Fixnum] The damage achieved with this weapon
+  attr_reader :damage
+
+  # Returns the damage dealt to team mates with this weapon
+  #
+  # @return [Fixnum] The damage dealt to team mates with this weapon
+  attr_reader :friendly_fire
+
+  # Returns the name of this weapon
+  #
+  # @return [String] The name of this weapon
+  attr_reader :name
 
-  # Creates a new instance of AlienSwarmWeapon based on the assigned weapon
-  # XML data
+  # Creates a new weapon instance based on the assigned weapon XML data
+  #
+  # @param [REXML::Element] weapon_data The data representing this weapon
   def initialize(weapon_data)
     super
 

data/lib/steam/community/app_news.rb

@@ -1,61 +1,125 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2010, Sebastian Staudt
+# Copyright (c) 2010-2011, Sebastian Staudt
 
-require 'json'
+require 'multi_json'
 
 require 'steam/community/web_api'
 
-# The AppNews class is a representation of Steam news and can be used to load
-# current news about specific games
+# This class represents Steam news and can be used to load a list of current
+# news about specific games
+#
+# @author Sebastian Staudt
 class AppNews
 
-  attr_reader :app_id, :author, :contents, :date, :feed_label, :feed_name,
-              :gid, :title, :url
+  # Returns the Steam Application ID of the game this news belongs to
+  #
+  # @return [Fixnum] The application ID of the game this news belongs to
+  attr_reader :app_id
+
+  # Returns the name of the author of this news
+  #
+  # @return [String] The author of this news
+  attr_reader :author
+
+  # Returns the contents of this news
+  #
+  # This might contain HTML code.
+  #
+  # @note Depending on the setting for the maximum length of a news (see
+  #       {.news_for_app}), the contents might be truncated.
+  # @return [String] The contents of this news
+  attr_reader :contents
+
+  # Returns the date this news item has been published
+  #
+  # @return [Time] The date this news has been published
+  attr_reader :date
+
+  # Returns the name of the feed this news item belongs to
+  #
+  # @return [String] The name of the feed this news belongs to
+  attr_reader :feed_label
+
+  # Returns the symbolic name of the feed this news item belongs to
+  #
+  # @return [String] The symbolic name of the feed this news belongs to
+  attr_reader :feed_name
+
+  # Returns a unique identifier for this news
+  #
+  # @return [Fixnum] A unique identifier for this news
+  attr_reader :gid
+
+  # Returns the title of this news
+  #
+  # @return [String] The title of this news
+  attr_reader :title
+
+  # Returns the URL of the original news
+  #
+  # This is a direct link to the news on the Steam website or a redirecting
+  # link to the external post.
+  #
+  # @return [String] The URL of the original news
+  attr_reader :url
 
   # Loads the news for the given game with the given restrictions
   #
-  # [+app_id+]     The unique Steam Application ID of the game (e.g. +440+ for
-  #                Team Fortress 2). See
-  #                http://developer.valvesoftware.com/wiki/Steam_Application_IDs
-  #                for all application IDs
-  # [+count+]      The maximum number of news to load (default: 5). There's no
-  #                reliable way to load all news. Use really a really great
-  #                number instead
-  # [+max_length+] The maximum content length of the news (default: nil). If a
-  #                maximum length is defined, the content of the news will only
-  #                be at most +max_length+ characters long plus an ellipsis
+  # @param [Fixnum] app_id The unique Steam Application ID of the game (e.g.
+  #        `440` for Team Fortress 2). See
+  #        http://developer.valvesoftware.com/wiki/Steam_Application_IDs for
+  #        all application IDs.
+  # @param [Fixnum] count The maximum number of news to load. There's no
+  #        reliable way to load all news. Use a really great number instead.
+  # @param [Fixnum] max_length The maximum content length of the news. If a
+  #        maximum length is defined, the content of the news will only be at
+  #        most `max_length` characters long plus an ellipsis.
+  # @return [Array<AppNews>] An array of news items for the specified game with
+  #         the given options
   def self.news_for_app(app_id, count = 5, max_length = nil)
     params = { :appid => app_id, :count => count, :maxlength => max_length }
-    data = WebApi.json('ISteamNews', 'GetNewsForApp', 1, params)
+    data = WebApi.json('ISteamNews', 'GetNewsForApp', 2, params)
 
     news_items = []
-    JSON.parse(data, { :symbolize_names => true })[:appnews][:newsitems][:newsitem].each do |news_data|
+    MultiJson.decode(data, { :symbolize_keys => true })[:appnews][:newsitems].each do |news_data|
       news_items << AppNews.new(app_id, news_data)
     end
 
     news_items
   end
 
-  # Returns whether this news items originates from a source other than Steam
+  # Returns whether this news item originates from a source other than Steam
   # itself (e.g. an external blog)
+  #
+  # @return [Boolean] `true` if this news item is from an external source
   def external?
     @external
   end
 
+  # Returns a simple textual representation of this news item
+  #
+  # Will consist of the name of the feed this news belongs to and the title of
+  # the news.
+  #
+  # @return [String] A simple text representing this news
+  def to_s
+    "#{@feed_label}: #{@title}"
+  end
+
   private
 
   # Creates a new instance of an AppNews news item with the given data
   #
-  # [+app_id+]    The unique Steam Application ID of the game (e.g. +440+ for
-  #               Team Fortress 2). See
-  #               http://developer.valvesoftware.com/wiki/Steam_Application_IDs
-  #               for all application IDs
-  # [+news_data+] The news data extracted from JSON
+  # @param [Fixnum] app_id The unique Steam Application ID of the game (e.g.
+  #        `440` for Team Fortress 2). See
+  #        http://developer.valvesoftware.com/wiki/Steam_Application_IDs for
+  #        all application IDs.
+  # @param [Hash<Symbol, Object>] news_data The news data extracted from JSON
   def initialize(app_id, news_data)
     @app_id      = app_id
-    @author      = news_data[:autor]
+    @author      = news_data[:author]
     @contents    = news_data[:contents].strip
     @data        = Time.at(news_data[:date])
     @external    = news_data[:is_external_url]

data/lib/steam/community/cacheable.rb

@@ -1,14 +1,26 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
-# This module implements caching functionality to be used in any object using a
-# +fetch+ method to fetch data, e.g. using a HTTP download.
+# This module implements caching functionality to be used in any object class
+# having one or more unique object identifier (i.e. ID) and using a `fetch`
+# method to fetch data, e.g. using a HTTP download.
+#
+# @author Sebastian Staudt
 module Cacheable
 
-  def self.included(base) #:nodoc:
-
+  # When this module is included in another class it is initialized to make use
+  # of caching
+  #
+  # The original `new` method of the including class will be aliased with
+  # `create`, relaying all instantiations to the `new` method defined in
+  # {ClassMethods}. Additionally the class variable to save the attributes to
+  # cache (i.e. cache IDs) and the cache class variable itself are initialized.
+  #
+  # @param [Class] base The class to extend with caching functionality
+  # @see ClassMethods
+  def self.included(base)
     base.extend ClassMethods
     base.send :class_variable_set, :@@cache, {}
     base.send :class_variable_set, :@@cache_ids, []
@@ -16,32 +28,50 @@ module Cacheable
     class << base
       alias_method :create, :new
     end
-
   end
 
+  # This module implements functionality to access the cache of a class that
+  # includes the {Cacheable} module as class methods
+  #
+  # @author Sebastian Staudt
   module ClassMethods
 
-    # Defines wich instance variables should be used to index the cached objects
-    # A call to this method is needed, if you want a class including this module
-    # to really use the cache.
+    # Defines wich instance variables which should be used to index the cached
+    # objects
+    #
+    # @note A call to this method is needed if you want a class including this
+    #       module to really use the cache.
+    # @param [Array<Symbol>] ids The symbolic names of the instance variables
+    #        representing a unique identifier for this object class
     def cacheable_with_ids(*ids)
       class_variable_set(:@@cache_ids, ids)
     end
 
-    # Returns whether the requested object +id+ is already cached
+    # Returns whether an object with the given ID is already cached
+    #
+    # @param [Object] id The ID of the desired object
+    # @return [Boolean] `true` if the object with the given ID is already
+    #         cached
     def cached?(id)
       id.downcase! if id.is_a? String
       class_variable_get(:@@cache).key?(id)
     end
 
-    # Clears the object cache
+    # Clears the object cache for the class this method is called on
     def clear_cache
       class_variable_set :@@cache, {}
     end
 
-    # This checks the cache for an existing object. If it exists it is returned.
-    # Otherwise a new object is created.
-    # Overrides the default constructor.
+    # This checks the cache for an existing object. If it exists it is
+    # returned, otherwise a new object is created.
+    # Overrides the default `new` method of the cacheable object class.
+    #
+    # @param [Object] id The ID of the object that should be loaded
+    # @param [Boolean] fetch whether the object's data should be retrieved
+    # @param [Boolean] bypass_cache whether the object should be loaded again
+    #        even if it is already cached
+    # @see #cached?
+    # @see #fetch
     def new(id, fetch = true, bypass_cache = false)
       if cached?(id) && !bypass_cache
         object = class_variable_get(:@@cache)[id]
@@ -54,18 +84,25 @@ module Cacheable
 
   end
 
+  # Returns the time the object's data has been fetched the last time
+  #
+  # @return [Time] The time the object has been updated the last time
   attr_reader :fetch_time
 
-  # Creates a new object for the given +id+, either numeric or
-  # the custom URL specified by the user. If +fetch_now+ is +true+ (default),
-  # fetch is used to load data into the object.
-  # This method is overridden by Cacheable::ClassMethods#new.
+  # Creates a new object and fetches the associated data of the object if
+  # desired
+  #
+  # @note The real constructor of cacheable classes is {ClassMethods#new}.
+  # @param [Boolean] fetch_now If `true`, the object's {#fetch} method is
+  #        called to retrieve its data
   def initialize(fetch_now = true) #:notnew:
     fetch if fetch_now
     cache
   end
 
   # Saves this object in the cache
+  #
+  # This will use the ID attributes selected for caching
   def cache
     cache     = self.class.send :class_variable_get, :@@cache
     cache_ids = self.class.send :class_variable_get, :@@cache_ids
@@ -81,11 +118,18 @@ module Cacheable
   end
 
   # Sets the time this object has been fetched the last time
+  #
+  # @note This method should be overridden in cacheable object classes and
+  #       should implement the logic to retrieve the object's data. The
+  #       overriding method should always call `super` to have the fetch time
+  #       up-to-date.
   def fetch
     @fetch_time = Time.now
   end
 
-  # Returns whether the data for this SteamID has already been fetched
+  # Returns whether the data for this object has already been fetched
+  #
+  # @return [Boolean] `true` if this object's data is available
   def fetched?
     !@fetch_time.nil?
   end

data/lib/steam/community/css/css_map.rb

@@ -1,17 +1,38 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2010, Sebastian Staudt
+# Copyright (c) 2010-2011, Sebastian Staudt
 
-# CSSMap holds statistical information about maps played by a player in
-# Counter-Strike: Source.
+# Represents the stats for a Counter-Strike: Source map for a specific user
+#
+# @author Sebastian Staudt
 class CSSMap
 
-  attr_reader :name, :rounds_lost, :rounds_played, :rounds_won,
-              :rounds_won_percentage
+  # Returns the name of this map
+  #
+  # @return [String] The name of this map
+  attr_reader :name
+
+  # Returns the number of rounds the player has lost on this map
+  #
+  # @return [Fixnum] The number of rounds lost
+  attr_reader :rounds_lost
+
+  # Returns the number of rounds the player has played on this map
+  #
+  # @return [Fixnum] The number of rounds played
+  attr_reader :rounds_played
 
-  # Creates a new instance of CSSMap based on the assigned map name and XML
-  # data
+  # Returns the number of rounds the player has won on this map
+  #
+  # @return [Fixnum] The number of rounds won
+  attr_reader :rounds_won
+
+  # Creates a new instance of a Counter-Strike: Source class based on the
+  # given XML data
+  #
+  # @param [String] map_name The name of the map
+  # @param [REXML::Element] maps_data The XML data of all maps
   def initialize(map_name, maps_data)
     @name          = map_name
 
@@ -24,8 +45,17 @@ class CSSMap
   end
 
   # Returns whether this map is the favorite map of this player
+  #
+  # @return [Boolean] `true` if this is the favorite map
   def favorite?
     @favorite
   end
 
+  # Returns the percentage of rounds the player has won on this map
+  #
+  # @return [Float] The percentage of rounds won
+  def rounds_won_percentage
+    (@rounds_played > 0) ? @rounds_won.to_f / @rounds_played : 0
+  end
+
 end

data/lib/steam/community/css/css_stats.rb

@@ -1,29 +1,44 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
 # Copyright (c) 2010, Sebastian Staudt
 
 require 'steam/community/css/css_map'
 require 'steam/community/css/css_weapon'
 
-# The CSSStats class represents the game statistics for a single user in
+# The is class represents the game statistics for a single user in
 # Counter-Strike: Source
+#
+# @author Sebastian Staudt
 class CSSStats < GameStats
 
+  # The names of the maps in Counter-Strike: Source
   MAPS = [ 'cs_assault', 'cs_compound', 'cs_havana', 'cs_italy', 'cs_militia',
            'cs_office', 'de_aztec', 'de_cbble', 'de_chateau', 'de_dust',
            'de_dust2', 'de_inferno', 'de_nuke', 'de_piranesi', 'de_port',
            'de_prodigy', 'de_tides', 'de_train' ]
 
+  # The names of the weapons in Counter-Strike: Source
   WEAPONS = [ 'deagle', 'usp', 'glock', 'p228', 'elite', 'fiveseven', 'awp',
               'ak47', 'm4a1', 'aug', 'sg552', 'sg550', 'galil', 'famas',
               'scout', 'g3sg1', 'p90', 'mp5navy', 'tmp', 'mac10', 'ump45',
               'm3', 'xm1014', 'm249', 'knife', 'grenade' ]
 
-  attr_reader :last_match_stats, :total_stats
-
-  # Creates a CSSStats object by calling the super constructor with the game
-  # name "cs:s"
+  # Returns statistics about the last match the player played
+  #
+  # @return [Hash<Symbol, Object>] The stats of the last match
+  attr_reader :last_match_stats
+
+  # Returns overall statistics of this player
+  #
+  # @return [Hash<Symbol, Object>] The overall statistics
+  attr_reader :total_stats
+
+  # Creates a <var>CSSStats</var> instance by calling the super constructor
+  # with the game name <var>"cs:s"</var>
+  #
+  # @param [String, Fixnum] steam_id The custom URL or 64bit Steam ID of the
+  #        user
   def initialize(steam_id)
     super steam_id, 'cs:s'
 
@@ -78,8 +93,11 @@ class CSSStats < GameStats
     end
   end
 
-  # Returns a Hash of CSSMap for this user containing all Counter-Strike:
-  # Source maps. If the maps haven't been parsed already, parsing is done now.
+  # Returns a map of `CSSMap` for this user containing all CS:S maps.
+  #
+  # If the maps haven't been parsed already, parsing is done now.
+  #
+  # @return [Hash<String, Object>] The map statistics for this user
   def map_stats
     return unless public?
 
@@ -95,9 +113,11 @@ class CSSStats < GameStats
     @map_stats
   end
 
-  # Returns a Hash of CSSWeapon for this user containing all Counter-Strike:
-  # Source weapons. If the weapons haven't been parsed already, parsing is done
-  # now.
+  # Returns a map of `CSSWeapon` for this user containing all CS:S weapons.
+  #
+  # If the weapons haven't been parsed already, parsing is done now.
+  #
+  # @return [Hash<String, Object>] The weapon statistics for this user
   def weapon_stats
     return unless public?