From 9ed908f44ae91988a26ba7e9f1cee15ebe253a07 Mon Sep 17 00:00:00 2001
From: Dave Collins <davec@conformal.com>
Date: Tue, 8 Jul 2014 08:45:37 -0500
Subject: [PATCH] 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       | 35 +++++++----------------------------
 doc.go          | 26 +-------------------------
 example_test.go | 42 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 53 deletions(-)
 create mode 100644 example_test.go

diff --git a/README.md b/README.md
index eb05c1ed..813eee02 100644
--- a/README.md
+++ b/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%
 
diff --git a/doc.go b/doc.go
index 5a89f75d..559428ff 100644
--- a/doc.go
+++ b/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:
-
-	// 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
-	}
+referenced parent block to already exist.
 */
 package btcdb
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 00000000..eda1c0d1
--- /dev/null
+++ b/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
+}