Use testable example and update README.md.

This commit moves the example to a test file so it integrates nicely with
Go's example tooling.

This allows the example output to be tested as a part of running the
normal Go tests to help ensure it doesn't get out of date with the code.
It is also nice to have the example in one place rather than repeating it
in doc.go and README.md.

Links and information about the example have been included in README.md in
place of the example.

README.md

@@ -10,34 +10,6 @@ See `test_coverage.txt` for the current coverage (using gocov).  Alternatively,
 if you are running a POSIX OS, you can run the cov_report.sh script for a
 real-time report.  Package btcdb is licensed under the liberal ISC license.
 
-## Sample Use
-
-```Go
-	// Import packages.
-	import (
-		"github.com/conformal/btcdb"
-		_ "github.com/conformal/btcdb/ldb"
-		"github.com/conformal/btcnet"
-		"github.com/conformal/btcutil"
-	)
-
-	// Create a database and schedule it to be closed on exit.
-	dbName := "example"
-	db, err := btcdb.CreateDB("leveldb", dbName)
-	if err != nil {
-		// Log and handle the error
-	}
-	defer db.Close()
-
-
-	// Insert the main network genesis block.
-	genesis := btcutil.NewBlock(btcnet.MainNetParams.GenesisBlock)
-	newHeight, err := db.InsertBlock(genesis)
-	if err != nil {
-		// Log and handle the error
-	}
-```
-
 ## Documentation
 
 [![GoDoc](https://godoc.org/github.com/conformal/btcdb?status.png)]
@@ -57,6 +29,13 @@ http://localhost:6060/pkg/github.com/conformal/btcdb
 $ go get github.com/conformal/btcdb
 ```
 
+## Examples
+
+* [CreateDB Example]
+  (http://godoc.org/github.com/conformal/btcdb#example-CreateDB)  
+  Demonstrates creating a new database and inserting the genesis
+  block into it.
+
 ## TODO
 - Increase test coverage to 100%
 

doc.go

@@ -27,30 +27,6 @@ At the highest level, the use of this packages just requires that you
 import it, setup a database, insert some data into it, and optionally,
 query the data back.  The first block inserted into the database will be
 treated as the genesis block.  Every subsequent block insert requires the
-referenced parent block to already exist.  In a more concrete example:
+referenced parent block to already exist.
-
-	// Import packages.
-	import (
-		"github.com/conformal/btcdb"
-		_ "github.com/conformal/btcdb/ldb"
-		"github.com/conformal/btcnet"
-		"github.com/conformal/btcutil"
-	)
-
-	// Create a database and schedule it to be closed on exit.
-	dbName := "example.db"
-	db, err := btcdb.CreateDB("leveldb", dbName)
-	if err != nil {
-		// Log and handle the error
-	}
-	defer db.Close()
-
-
-	// Insert the main network genesis block.
-	genesis := btcutil.NewBlock(btcnet.MainNetParams.GenesisBlock)
-	newHeight, err := db.InsertBlock(genesis)
-	if err != nil {
-		// Log and handle the error
-	}
 */
 package btcdb

example_test.go

@@ -0,0 +1,42 @@
+// Copyright (c) 2013-2014 Conformal Systems LLC.
+// Use of this source code is governed by an ISC
+// license that can be found in the LICENSE file.
+
+package btcdb_test
+
+import (
+	"fmt"
+	"github.com/conformal/btcdb"
+	_ "github.com/conformal/btcdb/memdb"
+	"github.com/conformal/btcnet"
+	"github.com/conformal/btcutil"
+)
+
+// This example demonstrates creating a new database and inserting the genesis
+// block into it.
+func ExampleCreateDB() {
+	// Create a database and schedule it to be closed on exit.  This example
+	// uses a memory-only database to avoid needing to write anything to
+	// the disk.  Typically, you would specify a persistent database driver
+	// such as "leveldb" and give it a database name as the second
+	// parameter.
+	db, err := btcdb.CreateDB("memdb")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer db.Close()
+
+	// Insert the main network genesis block.
+	genesis := btcutil.NewBlock(btcnet.MainNetParams.GenesisBlock)
+	newHeight, err := db.InsertBlock(genesis)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	fmt.Println("New height:", newHeight)
+
+	// Output:
+	// New height: 0
+}