From 184735e6893267ed02f26b88a71c73a07a263035 Mon Sep 17 00:00:00 2001
From: Alec Thomas <alec@swapoff.org>
Date: Sun, 20 May 2018 00:42:54 +1000
Subject: [PATCH] Document how decoders work.

---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index 5ef36e4..143d108 100644
--- a/README.md
+++ b/README.md
@@ -24,3 +24,24 @@ func main() {
   kong.Parse(&CLI)
 }
 ```
+
+## Decoders
+
+Command-line arguments are mapped to Go values via the Decoder interface:
+
+```go
+// A Decoder knows how to decode text into a Go value.
+type Decoder interface {
+	// Decode scan into target.
+	//
+	// "ctx" contains context about the value being decoded that may be useful
+	// to some decoders.
+	Decode(ctx *DecoderContext, scan *Scanner, target reflect.Value) error
+}
+```
+
+All builtin Go types (as well as a bunch of useful stdlib types like `time.Time`) have decoders registered by default. Decoders for custom types can be added using `kong.RegisterDecoder(decoder)`. Decoders are mapped from fields in three ways:
+
+1. By registering a `kong.NamedDecoder` and using the tag `type:"<name>"`.
+2. By registering a `kong.KindDecoder` with a `reflect.Kind`.
+3. By registering a `kong.TypeDecoder` with a `reflect.Type`.