Add tutorial

Author: korthaj

example_test.go

@@ -6,7 +6,7 @@ import (
 	"math"
 )
 
-// Create, combine, compare and print bit arrays.
+// Create, combine, compare and print bit sets.
 func Example_basics() {
 	// Add all elements in the range [0, 100) to the empty set.
 	A := new(bit.Set).AddRange(0, 100) // {0..99}
@@ -30,7 +30,7 @@ func Example_basics() {
 
 // Create the set of all primes less than n in O(n log log n) time.
 // Try the code with n equal to a few hundred millions and be pleasantly surprised.
-func Example_eratosthenes() {
+func Example_primes() {
 	// Sieve of Eratosthenes
 	const n = 50
 	sieve := bit.New().AddRange(2, n)

set.go

@@ -11,11 +11,22 @@
 //
 // Bit set
 //
-// A bit array, or bit set, is an efficient set data structure
+// A bit set, or bit array, is an efficient set data structure
 // that consists of an array of 64-bit words. Because it uses
 // bit-level parallelism, limits memory access, and efficiently uses
 // the data cache, a bit set often outperforms other data structures.
 //
+// Tutorial
+//
+// The Basics example shows how to create, combine, compare and
+// print bit sets.
+//
+// Primes contains a short and simple, but still efficient,
+// implementation of a prime number sieve.
+//
+// Union is a more advanced example demonstrating how to build
+// an efficient variadic Union function using the SetOr method.
+//
 package bit
 
 import (