📝 Update docs and add example

CHANGELOG.md

@@ -1,3 +1,9 @@
 ## 1.0.0
 
-- 
+- Load suffix rule lists from strings or URIs.
+- Parse URLs against suffix lists to obtain:
+    - public suffix (e.g. `co.uk`)
+    - root domain (e.g. `google`)
+    - registrable domain (e.g. `google.co.uk`)
+- Obtain results with and without private (i.e. non-ICANN/IANA) suffix rules.
+- Obtain punycode encoded and decoded results (if a punycoded URL is parsed).

README.md

@@ -1,25 +1,43 @@
 # public_suffix
+[![Build Status](https://travis-ci.com/Komposten/public_suffix.svg?branch=master)](https://travis-ci.com/Komposten/public_suffix)
+
 **A domain parser based on the [Public Suffix List](https://publicsuffix.org/)**
 
-public_suffix identifies the public suffixes, root domains and registrable parts of URLs.
+public_suffix is a dart library for identifying the public suffixes (or TLDs), root domains and registrable parts of URLs.
 
 ## Usage
 1) Import `public_suffix_io.dart` or `public_suffix_browser.dart`.
 2) Initialise `SuffixRules` from a file/uri containing suffix rules.
 3) Create a new instance of `PublicSuffix` to parse a URL.
+4) Access the different components through the `PublicSuffix` object.
+
+**Note:** Don't overload publicsuffix.org's servers by repeatedly retrieving the suffix list from them. Cache a copy somewhere instead, and update that copy only when the master copy is updated.
 
 ```dart
-import 'public_suffix_io.dart';
-
-main() {
-  SuffixRulesHelper.initFromUri(Uri.parse("https://publicsuffix.org/list/public_suffix_list.dat"));
-  PublicSuffix suffix = PublicSuffix(Uri.parse("https://www.publicsuffix.org"));
-  
-  print(suffix.publicTld); // "org"
-  print(suffix.rootDomain); // "publicsuffix"
-  print(suffix.registrableDomain); // "publicsuffix.org"
+import 'package:public_suffix/public_suffix_io.dart';
+
+main(List<String> arguments) async {
+  await SuffixRulesHelper.initFromUri(
+      Uri.parse("https://publicsuffix.org/list/public_suffix_list.dat"));
+  PublicSuffix suffix =
+      PublicSuffix(Uri.parse("https://www.komposten.github.io"));
+
+  //Results when matching against ICANN/IANA and private suffixes.
+  print(suffix.suffix); // "github.io"
+  print(suffix.root); // "komposten"
+  print(suffix.domain); // "komposten.github.io"
+
+  //Results when matching against only ICANN/IANA suffixes.
+  print(suffix.icannSuffix); // "io"
+  print(suffix.icannRoot); // "github"
+  print(suffix.icannDomain); // "github.io"
+
+  //punycode decoded results.
+  suffix = PublicSuffix(Uri.parse("https://www.xn--6qq79v.cn"));
+  print(suffix.domain); // "xn--6qq79v.cn"
+  print(suffix.punyDecoded.domain); // "你好.cn"
 }
 ```
 
 ## License
-public_suffix is licensed under the MIT license. See [LICENSE](LICENSE) for the full license text.
+public_suffix is licensed under the MIT license. See [LICENSE](https://github.com/Komposten/public_suffix/blob/master/LICENSE) for the full license text.

example/main.dart

@@ -0,0 +1,30 @@
+import 'package:public_suffix/public_suffix_io.dart';
+
+main(List<String> arguments) async {
+  // Load a list of suffix rules from publicsuffix.org.
+  await SuffixRulesHelper.initFromUri(
+      Uri.parse("https://publicsuffix.org/list/public_suffix_list.dat"));
+
+  // Parse a URL.
+  PublicSuffix suffix =
+      PublicSuffix(Uri.parse("https://www.komposten.github.io"));
+
+  // Results when matching against ICANN/IANA and private suffixes.
+  print(suffix.suffix); // "github.io"
+  print(suffix.root); // "komposten"
+  print(suffix.domain); // "komposten.github.io"
+
+  // Results when matching against only ICANN/IANA suffixes.
+  print(suffix.icannSuffix); // "io"
+  print(suffix.icannRoot); // "github"
+  print(suffix.icannDomain); // "github.io"
+
+  // punycode decoded results.
+  suffix = PublicSuffix(Uri.parse("https://www.xn--6qq79v.cn"));
+  print(suffix.domain); // "xn--6qq79v.cn"
+  print(suffix.punyDecoded.domain); // "你好.cn"
+
+  // Dispose the list to unload it from memory if you wish.
+  // This is probably not needed since the list is relatively small.
+  SuffixRules.dispose();
+}

pubspec.yaml

@@ -1,6 +1,6 @@
 name: public_suffix
-description: A library for getting the public suffix of a URL.
-# version: 1.0.0
+description: A domain parser based on the Public Suffix List
+version: 1.0.0
 homepage: https://www.github.com/komposten/
 repository: https://www.github.com/komposten/public_suffix
 issue_tracker: https://www.github.com/komposten/public_suffix/issues