Doc: clarify errors returned by Decode (#713)

Fixes #625

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
+When most decoding errors occur, go-toml returns [`DecodeError`][decode-err]),
-contains a human readable contextualized version of the error. For example:
+which contains a human readable contextualized version of the error. For
+example:
 
 ```
 2| key1 = "value1"

errors_test.go

@@ -212,12 +212,12 @@ func ExampleDecodeError() {
 
 	fmt.Println(err)
 
-	//nolint:errorlint
+	var derr *DecodeError
-	de := err.(*DecodeError)
+	if errors.As(err, &derr) {
-	fmt.Println(de.String())
+		fmt.Println(derr.String())
-
+		row, col := derr.Position()
-	row, col := de.Position()
+		fmt.Println("error occurred at row", row, "column", col)
-	fmt.Println("error occurred at row", row, "column", col)
+	}
 	// Output:
 	// toml: number must have at least one digit between underscores
 	// 1| name = 123__456

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: