From d58eb50ebfb929b84ef2af730b2f8503aa4a25fb Mon Sep 17 00:00:00 2001
From: Thomas Pelletier <pelletier.thomas@gmail.com>
Date: Sun, 26 Dec 2021 20:04:09 +0100
Subject: [PATCH] Doc: clarify errors returned by Decode (#713)

Fixes #625
---
 README.md      |  5 +++--
 errors_test.go | 12 ++++++------
 unmarshaler.go |  5 +++++
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 6c539e9..b20d362 100644
--- a/README.md
+++ b/README.md
@@ -55,8 +55,9 @@ to check for typos. [See example in the documentation][strict].
 
 ### Contextualized errors
 
-When decoding errors occur, go-toml returns [`DecodeError`][decode-err]), which
-contains a human readable contextualized version of the error. For example:
+When most decoding errors occur, go-toml returns [`DecodeError`][decode-err]),
+which contains a human readable contextualized version of the error. For
+example:
 
 ```
 2| key1 = "value1"
diff --git a/errors_test.go b/errors_test.go
index 1c02595..c100353 100644
--- a/errors_test.go
+++ b/errors_test.go
@@ -212,12 +212,12 @@ func ExampleDecodeError() {
 
 	fmt.Println(err)
 
-	//nolint:errorlint
-	de := err.(*DecodeError)
-	fmt.Println(de.String())
-
-	row, col := de.Position()
-	fmt.Println("error occurred at row", row, "column", col)
+	var derr *DecodeError
+	if errors.As(err, &derr) {
+		fmt.Println(derr.String())
+		row, col := derr.Position()
+		fmt.Println("error occurred at row", row, "column", col)
+	}
 	// Output:
 	// toml: number must have at least one digit between underscores
 	// 1| name = 123__456
diff --git a/unmarshaler.go b/unmarshaler.go
index d3ff84c..acc9ef6 100644
--- a/unmarshaler.go
+++ b/unmarshaler.go
@@ -73,6 +73,11 @@ func (d *Decoder) SetStrict(strict bool) *Decoder {
 // bounds for the target type (which includes negative numbers when decoding
 // into an unsigned int).
 //
+// If an error occurs while decoding the content of the document, this function
+// returns a toml.DecodeError, providing context about the issue. When using
+// strict mode and a field is missing, a `toml.StrictMissingError` is
+// returned. In any other case, this function returns a standard Go error.
+//
 // Type mapping
 //
 // List of supported TOML types and their associated accepted Go types: