Documentation galore!

Author: cadwallion

README.md

@@ -0,0 +1,11 @@
+# BnetScraper
+
+A Nokogiri-based scraper of Battle.net profiles.  Currently this only includes Starcraft2.
+
+# Usage
+
+The gem allows you to parse profiles separate from individual leagues, using `BnetScraper::Starcraft2::ProfileScraper`
+or `BnetScraper::Starcraft2::LeagueScraper`.  See documentation for more information on those.
+
+One convenience function, `BnetScraper::Starcraft2#full_profile_scrape`, exists to do a full scrape of a given profile.
+Note that this is a rather slow function given the number of HTTP calls necessary to retrieve all of the data.

lib/bnet_scraper/starcraft2.rb

@@ -2,6 +2,9 @@
 require 'bnet_scraper/starcraft2/league_scraper'
 
 module BnetScraper
+  # This module contains everything about scraping Starcraft 2 Battle.net accounts.
+  # See `BnetScraper::Starcraft2::ProfileScraper` and `BnetScraper::Starcraft2::LeagueScraper`
+  # for more details
   module Starcraft2
     REGIONS = {
       'na'  => { domain: 'us.battle.net', dir: 'en' },
@@ -11,6 +14,19 @@ module Starcraft2
       'fea' => { domain: 'tw.battle.net', dir: 'zh' } 
     }
 
+    # This is a convenience method that chains calls to ProfileScraper,
+    # followed by a scrape of each league returned in the `leagues` array
+    # in the profile_data.  The end result is a fully scraped profile with
+    # profile and league data in a hash.
+    #
+    # See `BnetScraper::Starcraft2::ProfileScraper` for more information on
+    # the parameters being sent to `#full_profile_scrape`.
+    #
+    # @param bnet_id - Battle.net Account ID 
+    # @param account - Battle.net Account Name
+    # @param region  - Battle.net Account Region
+    # @return profile_data - Hash containing complete profile and league data
+    #   scraped from the website
     def self.full_profile_scrape bnet_id, account, region = 'na'
       profile_scraper = ProfileScraper.new bnet_id, account, region
       profile_output  = profile_scraper.scrape

lib/bnet_scraper/starcraft2/league_scraper.rb

@@ -1,5 +1,14 @@
 module BnetScraper
   module Starcraft2
+    # LeagueScraper
+    #
+    # 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
     class LeagueScraper
       attr_reader :url, :bnet_id, :bnet_index, :account, :league_id, :lang,
         :season, :size, :random, :name, :division

lib/bnet_scraper/starcraft2/profile_scraper.rb

@@ -1,15 +1,37 @@
 module BnetScraper
   module Starcraft2
+    # ProfileScraper
+    #
+    # 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.
     class ProfileScraper
       attr_reader :bnet_id, :account, :region, :agent, :bnet_index
 
+      # @param bnet_id - The unique ID for each battle.net account. in the URL scheme, it immediately
+      #   follows the /profile/ directive.
+      # @param account - The account name.  This is a non-unique string that immediately follows the
+      #   bnet_index
+      # @oaram region - The region of the account.  This defaults to 'na' for North America. This
+      #   uses the bnet region codes instead of the full names. The region is used to determine the
+      #   domain to find the profile, as well as teh default language code to use.
+      # @return profile_data - The hash of profile data scraped, including array of leagues to scrape
       def initialize bnet_id, account, region = 'na'
         @bnet_id  = bnet_id
         @account  = account
         @region   = region
         set_bnet_index
       end
 
+      # set_bnet_index
+      # 
+      # Because profile URLs have to have a specific bnet_index that is seemingly incalculable,
+      # we must ping both variants to determine the correct bnet_index. We then store that value.
       def set_bnet_index
         [1,2].each do |idx|
           res = Net::HTTP.get_response URI profile_url idx