diff --git a/mapstructure.go b/mapstructure.go
index 3a01f0e..151741c 100644
--- a/mapstructure.go
+++ b/mapstructure.go
@@ -28,7 +28,10 @@
 
 // A Decoder takes a raw interface value and turns it into structured
 // data, keeping track of rich error information along the way in case
-// anything goes wrong.
+// anything goes wrong. Unlike the basic top-level Decode method, you can
+// more finely control how the Decoder behaves using the DecoderConfig
+// structure. The top-level Decode method is just a convenience that sets
+// up the most basic Decoder.
 type Decoder struct {
 	config *DecoderConfig
 }
diff --git a/mapstructure_examples_test.go b/mapstructure_examples_test.go
index 7eaba0d..5faae12 100644
--- a/mapstructure_examples_test.go
+++ b/mapstructure_examples_test.go
@@ -84,6 +84,9 @@
 		"email": "foo@bar.com",
 	}
 
+	// For metadata, we make a more advanced DecoderConfig so we can
+	// more finely configure the decoder that is used. In this case, we
+	// just tell the decoder we want to track metadata.
 	var md Metadata
 	var result Person
 	config := &DecoderConfig{