added some documentation describing various classes

Mostly for myself so I can understand what is what next time I look at this :p

lib/bad_pigeon/elements/timeline_entry.rb

@@ -2,6 +2,13 @@
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents an "entry" which is a part of a timeline response. An entry in most cases is a wrapper for either one
+  # tweet or a group of connected tweets (e.g. a parent and a reply).
+  #
+  # Tweets can be extracted from an entry using ({#items}) method, which returns an array of tweets as instances of
+  # {BadPigeon::TimelineTweet} class.
+
   class TimelineEntry
     include Assertions
 

lib/bad_pigeon/elements/timeline_instruction.rb

@@ -2,6 +2,12 @@
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents an "instruction" which is a part of a timeline response. An instruction can be e.g. pinning one entry
+  # to the top or adding some number of entries to the list view.
+  #
+  # A timeline includes one or more "entries" ({BadPigeon::TimelineEntry}), most of which contain one or more tweets.
+
   class TimelineInstruction
     include Assertions
 

lib/bad_pigeon/elements/timeline_tweet.rb

@@ -2,6 +2,12 @@
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a single tweet in a timeline (may possibly include no data in some cases).
+  #
+  # Use the {#tweet} method to get an instance of {BadPigeon::Tweet}, which is the final tweet model from which you can
+  # extract specific fields or a properly formatted JSON representation.
+
   class TimelineTweet
     include Assertions
 

lib/bad_pigeon/har/har_archive.rb

@@ -2,6 +2,11 @@
 require 'json'
 
 module BadPigeon
+
+  # Represents a whole request archive bundle loaded from a *.har file.
+  # 
+  # An archive consists of some number of requests ({BadPigeon::HARRequest}).
+
   class HARArchive
     def initialize(data)
       @json = JSON.parse(data)

lib/bad_pigeon/har/har_request.rb

@@ -2,6 +2,15 @@
 require 'json'
 
 module BadPigeon
+
+  # Represents info about one request and response to it, including the complete response data ({#response_body},
+  # or {#response_json} for a parsed JSON form).
+  #
+  # Requests that may potentially include tweet data return true from the {#includes_tweet_data?} method. The JSON
+  # data from each such request represents a "timeline" and may be parsed using a specific timeline class like
+  # {BadPigeon::HomeTimeline} or {BadPigeon::UserTimeline}; the {BadPigeon::TIMELINE_TYPES} hash provides a mapping
+  # of GraphQL endpoint names to timeline classes, and the endpoint name can be read using {#endpoint_name} method.
+
   class HARRequest
     def initialize(json)
       @json = json

lib/bad_pigeon/models/tweet.rb

@@ -6,6 +6,11 @@
 require 'time'
 
 module BadPigeon
+
+  #
+  # A model that represents one tweet with an interface matching that from the original `twitter` Ruby gem.
+  #
+
   class Tweet
     include Assertions
     extend Assertions

lib/bad_pigeon/models/url_entity.rb

@@ -1,6 +1,11 @@
 require 'addressable/uri'
 
 module BadPigeon
+
+  #
+  # A model that represents a "URL entity" of a tweet (a shortened link with info about the shortened and original URL).
+  #
+
   class URLEntity
     def initialize(json)
       @json = json

lib/bad_pigeon/models/user.rb

@@ -1,4 +1,9 @@
 module BadPigeon
+
+  #
+  # A model that represents a user with an interface matching that from the original `twitter` Ruby gem.
+  #
+
   class User
     attr_reader :json
 

lib/bad_pigeon/timelines/home_timeline.rb

@@ -2,6 +2,12 @@
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a timeline response for user's "For You" or "Following" timeline.
+  #
+  # A timeline includes one or more "instructions" ({BadPigeon::TimelineInstruction}), and usually in particular a
+  # "TimelineAddEntries" instruction which provides one or more entries containing tweets.
+
   class HomeTimeline
     include Assertions
 

lib/bad_pigeon/timelines/list_timeline.rb

@@ -2,6 +2,12 @@
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a timeline response for a list timeline.
+  #
+  # A timeline includes one or more "instructions" ({BadPigeon::TimelineInstruction}), and usually in particular a
+  # "TimelineAddEntries" instruction which provides one or more entries containing tweets.
+
   class ListTimeline
     include Assertions
 

lib/bad_pigeon/timelines/user_timeline.rb

@@ -2,6 +2,12 @@
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a timeline response for a timeline of user's posts as seen on their profile page.
+  #
+  # A timeline includes one or more "instructions" ({BadPigeon::TimelineInstruction}), and usually in particular a
+  # "TimelineAddEntries" instruction which provides one or more entries containing tweets.
+
   class UserTimeline
     include Assertions
 

lib/bad_pigeon/tweet_extractor.rb

@@ -6,6 +6,10 @@
 require 'uri'
 
 module BadPigeon
+
+  # The main entry point to the library. Pass the contents of a HAR archive file to {#get_tweets_from_har} and get
+  # a flat list of all extracted tweets in return.
+
   class TweetExtractor
     include Assertions