README.rdoc in public-suffix-list-0.0.6 vs README.rdoc in public-suffix-list-0.1.0

@@ -9,38 +9,56 @@
 a list is necessary because "there was and remains no algorithmic
 method of finding the highest level at which a domain may be
 registered for a particular top-level domain (the policies differ with
 each registry)...". Public Suffix List is also a small Ruby library
 designed to make the Public Suffix List (http://publicsuffix.org/)
-easier to use.
+easier to use.  Public Suffix List will transparently download the
+latest list of top-level domains, parse the list, and optionally cache
+the parsed data.
 
+The public API is as simple as I could make it.  Instantiating the
+PublicSuffixList class downloads, parses, and caches the data.  There
+are three instance methods:
+
+[*tld*(domain)] return the top-level domain name
+[*cdn*(domain)] return the canonical domain name
+[*split*(domain)] split the domain name into parts
+
 == Features
 
 * Transparent download of the TLD data file
 * Optional caching of optimized, parsed TLD data
 * Tiny API
 
 == Synopsis
 
   require "public_suffix_list"
 
-  # downloads and parses the latest data file and returns "com"
+  # Downloads and parses the latest data file and returns "com".
   PublicSuffixList.new.tld("foobar.com")
 
-  # downloads and parses the latest data file and returns "foobar.com"
+  # Downloads and parses the latest data file and returns "foobar.com".
   PublicSuffixList.new.cdn("foobar.com")
 
-  # downloads and parses the latest data file, caches it in /tmp, returns ["abc", "xyz", "co.uk"]
+  # Downloads and parses the latest data file, caches it in /tmp,
+  # and returns ["abc", "xyz", "co.uk"].
   PublicSuffixList.new(:cache_dir => "/tmp").split("abc.xyz.co.uk")
 
-  # loads the cached data in /tmp and returns ["test", "nhs", "uk"]
-  PublicSuffixList.new(:cache_dir => "/tmp").split("test.nhs.uk")
+  # Loads the cached data in /tmp if it is less than 100 seconds old,
+  # downloads, parses, and caches it if it is older, and returns
+  # ["test", "nhs", "uk"].
+  PublicSuffixList.new(:cache_dir => "/tmp", :cache_expiry_period => 100).split("test.nhs.uk")
 
-  # you don't have to instantiate PublicSuffixList every time you use it, of course...
+  # You don't have to instantiate PublicSuffixList every time you
+  # use it, of course...
   p = PublicSuffixList.new
   p.split("fee.fi.fo.com") # => ["fee.fi", "fo", "com"]
   p.cdn("fee.fi.fo.com")   # => "fo.com", "cdn" is "canonical domain name"
   p.tld("fee.fi.fo.com")   # => "com", "tld" is "top-level domain"
+
+  # You can even use other data files, both local and remote
+  # (as long as they conform to the Public Suffix List file format).
+  PublicSuffixList.new(:url => "spec/test.dat")
 
 == Requirements
 
 None that I am aware of.