Updates documentation of scrapers

[ci skip]

Author: cadwallion

lib/bnet_scraper/starcraft2/achievement_scraper.rb

@@ -1,5 +1,35 @@
 module BnetScraper
   module Starcraft2
+    # This pulls achievement information for an account.  Note that currently only returns the overall achievements,
+    # not the in-depth, by-category achievement information.
+    #
+    #  scraper = BnetScraper::Starcraft2::AchievementScraper.new(url: 'http://us.battle.net/sc2/en/profile/2377239/1/Demon/')
+    #  scraper.scrape
+    #  # => {
+    #    recent: [
+    #      { title: 'Blink of an Eye', description: 'Complete round 24 in "Starcraft Master" without losing any stalkers', earned: '3/5/2012' },
+    #      { title: 'Whack-a-Roach', description: 'Complete round 9 in "Starcraft Master" in under 45 seconds', earned: '3/5/2012' },
+    #      { title: 'Safe Zone', description: 'Complete round 8 in "Starcraft Master" without losing any stalkers', earned: '3/5/2012' },
+    #      { title: 'Starcraft Master', description: 'Complete all 30 rounds in "Starcraft Master"', earned: '3/5/2012' },
+    #      { title: 'Starcraft Expert', description: 'Complete any 25 rounds in "Starcraft Master"', earned: '3/5/2012' },
+    #      { title: 'Starcraft Apprentice', description: 'Complete any 20 rounds in "Starcraft Master"', earned: '3/5/2012' }
+    #    ],
+    #    showcase: [
+    #      { title: 'Hot Shot', description: 'Finish a Qualification Round with an undefeated record.' },
+    #      { title: 'Starcraft Master', description: 'Complete all rounds in "Starcraft Master"' },
+    #      { title: 'Team Protoss 500', description: 'Win 500 team league matches as Protoss' },
+    #      { title: 'Night of the Living III', description: 'Survive 15 Infested Horde Attacks in the "Night 2 Die" mode of the "Left 2 Die" scenario.' },
+    #      { title: 'Team Top 100 Diamond', description: 'Finish a Season in Team Diamond Division' }
+    #                          
+    #    ],
+    #    progress: {
+    #      liberty_campaign: '1580',
+    #      exploration: '480',
+    #      custom_game: '330',
+    #      cooperative: '660',
+    #      quick_match: '170'
+    #    }
+    #  }
     class AchievementScraper < BaseScraper
       attr_reader :recent, :progress, :showcase, :response
 
@@ -11,10 +41,12 @@ def scrape
         output
       end
 
+      # retrieves the account's achievements overview page HTML for scraping
       def get_response
         @response = Nokogiri::HTML(open(profile_url+"achievements/")) 
       end
 
+      # scrapes the recent achievements from the account's achievements overview page
       def scrape_recent
         @recent = []
         6.times do |num|
@@ -31,6 +63,7 @@ def scrape_recent
         @recent
       end
 
+      # scrapes the progress of each achievement category from the account's achievements overview page
       def scrape_progress
         progress_ach = response.css("#progress-module .achievements-progress:nth(2) span")
         @progress = {
@@ -42,6 +75,7 @@ def scrape_progress
         }
       end
 
+      # scrapes the showcase achievements from the account's achievements overview page
       def scrape_showcase
         @showcase = response.css("#showcase-module .progress-tile").map do |achievement|
           hsh = { title: achievement.css('.tooltip-title').inner_text.strip }

lib/bnet_scraper/starcraft2/base_scraper.rb

@@ -1,5 +1,19 @@
 module BnetScraper
   module Starcraft2
+    # BaseScraper handles the account information extraction. Each scraper can either be passed a profile URL or
+    # the minimum information needed to access an account.  This means passing in account and bnet_id at minimum.
+    # Both of the following are valid ways to instantiate a scraper for the same account:
+    #
+    #   BnetScraper::Starcraft2::BaseScraper.new(url: 'http://us.battle.net/sc2/en/profile/12345/1/TestAccount/')
+    #   BnetScraper::Starcraft2::BaseScraper.new(bnet_id: '12345', account: 'TestAccount')
+    #
+    # The URL scheme is the following:
+    #
+    #   http://<REGION_DOMAIN>/sc2/<REGION_LANG>/profile/<BNET_ID>/<BNET_INDEX>/<ACCOUNT>/
+    #
+    # Note that by default, the region will be set to 'na' if you opt not to specify the URL or region.  The 
+    # scraper uses the short-codes for regions. See `BnetScraper::Starcraft2::REGIONS` for the address 
+    # translations.
     class BaseScraper
       attr_reader :bnet_id, :account, :region, :bnet_index, :url
 
@@ -41,6 +55,8 @@ def profile_url bnet_index = @bnet_index
         "http://#{region_info[:domain]}/sc2/#{region_info[:dir]}/profile/#{bnet_id}/#{bnet_index}/#{account}/"
       end
 
+      # converts region short-code to region-based URL information
+      #   'na' => { domain: 'us.battle.net', :dir: 'en' }
       def region_info
         REGIONS[region] 
       end

lib/bnet_scraper/starcraft2/league_scraper.rb

@@ -1,17 +1,24 @@
 module BnetScraper
   module Starcraft2
-    # LeagueScraper
+    # This pulls information on a specific league for a specific account.  It is best used either in conjunction with a
+    # profile scrape that profiles a URL, or if you happen to know the specific league\_id and can pass it as an option.
     #
-    # Extracts information from an SC2 League URL and scrapes for information.
-    # Example:
-    #   league_data = BnetScraper::Starcraft2::LeagueScraper.new("http://us.battle.net/sc2/en/profile/2377239/1/Demon/ladder/96905")
-    #   league_data # => { bnet_id: '2377239', account: 'Demon', season: '6', size: '4v4', name: "Aleksander Pepper", division: "Diamond", random: false } 
-    #
-    # @param [String] url - The league URL on battle.net
-    # @return [Hash] league_data - Hash of data extracted
+    #  scraper = BnetScraper::Starcraft2::LeagueScraper.new(league_id: '12345', account: 'Demon', bnet_id: '2377239')
+    #  scraper.scrape
+    #  # => {
+    #    season: '6',
+    #    name: 'Aleksander Pepper',
+    #    division: 'Diamond',
+    #    size: '4v4',
+    #    random: false,
+    #    bnet_id: '2377239',
+    #    account: 'Demon'
+    #  }
     class LeagueScraper < BaseScraper
       attr_reader :league_id, :season, :size, :random, :name, :division
 
+      # @param [String] url - The league URL on battle.net
+      # @return [Hash] league_data - Hash of data extracted
       def initialize options = {}
         super(options)
 

lib/bnet_scraper/starcraft2/match_history_scraper.rb

@@ -1,7 +1,5 @@
 module BnetScraper
   module Starcraft2
-    ## BnetScraper::Starcraft2::MatchHistoryScraper
-    #
     # This pulls the 25 most recent matches played for an account. Note that this is only as up-to-date as battle.net is, and
     # will likely not be as fast as in-game.
     # 
@@ -20,10 +18,12 @@ module Starcraft2
     class MatchHistoryScraper < BaseScraper
       attr_reader :matches, :wins, :losses, :response
 
+      # account's match history URL
       def match_url
         profile_url + "matches"
       end
 
+      # retrieves the match history HTML for scraping
       def get_response
         @response = Nokogiri::HTML(open(match_url))
       end

lib/bnet_scraper/starcraft2/profile_scraper.rb

@@ -1,24 +1,25 @@
 module BnetScraper
   module Starcraft2
-    # ProfileScraper
+    # This pulls basic profile information for an account, as well as an array of league URLs.  This is a good starting
+    # point for league scraping as it provides the league URLs necessary to do supplemental scraping.
     #
-    # Scrapes SC2 profile data from battle.net and returns it as a hash.  Example:
-    #   profile_data = BnetScraper::Starcraft2::ProfileScraper.new('2377239', 'Demon')
-    #   profile_data # => { bnet_id: '2377239', account: 'Demon', race: 'Protoss', 
-    #                       wins: '684', achievements: '3260', leagues: [], bnet_index: 1 }
-    #
-    # One thing of note is the bnet_index. In Battle.net URLs, there is a single-digit index
-    # used on accounts (1 or 2).  This index is seemingly arbitrary, but critical to properly
-    # accessing the data.
-    #
-    # ProfileScraper requires that either you pass the URL of the profile, or the bnet_id and
-    # account name of the profile.  The URL scheme is as such:
-    #
-    #   http://<REGION_DOMAIN>/sc2/<REGION_LANG>/profile/<BNET_ID>/<BNET_INDEX>/<ACCOUNT>/
-    #
-    # Using this URL we can extract the critical information.  However, sometimes we do not have
-    # the URL and have to make do with a bnet_id and account.  This is the bare minimum needed,
-    # unless the account is in a region other than 'na'.  In such cases, region all needs to be passed.
+    #   scraper = BnetScraper::Starcraft2::ProfileScraper.new(url: 'http://us.battle.net/sc2/en/profile/2377239/1/Demon/')
+    #   scraper.scrape
+    #   # => {
+    #     bnet_id: '2377239',
+    #     account: 'Demon',
+    #     bnet_index: 1,
+    #     race: 'Protoss',
+    #     wins: '684',
+    #     achievement_points: '3630',
+    #     leagues: [
+    #       {
+    #         name: "1v1 Platinum Rank 95",
+    #         id:   "96905",
+    #         href: "http://us.battle.net/sc2/en/profile/2377239/1/Demon/ladder/96905#current-rank"
+    #       }
+    #     ]
+    #   }
     class ProfileScraper < BaseScraper
       attr_reader :achievement_points, :wins, :race, :leagues
       def scrape
@@ -27,6 +28,7 @@ def scrape
         output
       end
 
+      # scrapes the profile page for basic account information
       def get_profile_data
         response = Nokogiri::HTML(open(profile_url))
 
@@ -35,6 +37,7 @@ def get_profile_data
         @achievement_points = response.css("#profile-header h3").inner_html()
       end
 
+      # scrapes the league list from account's league page and sets an array of URLs
       def get_league_list
         response = Nokogiri::HTML(open(profile_url + "ladder/leagues"))