Improve docs

EXAMPLES.md

@@ -7,19 +7,22 @@
 ### Detect
 Get the MIME type from a slice of bytes, from a reader and from a file.
 ```go
+// Detect the MIME type of a file stored as a byte slice.
 file := "testdata/pdf.pdf"
-reader, _ := os.Open(file)       // ignoring error for brevity's sake
-data, _ := ioutil.ReadFile(file) // ignoring error for brevity's sake
-
-dmime := mimetype.Detect(data)
-rmime, rerr := mimetype.DetectReader(reader)
-fmime, ferr := mimetype.DetectFile(file)
+// Detect the MIME type of a file.
+mime, ferr := mimetype.DetectFile(file)
+fmt.Println(mime, ferr)
+// Output: application/pdf nil
 
-fmt.Println(dmime, rmime, fmime)
-fmt.Println(rerr, ferr)
+// Detect the MIME type of a reader.
+reader, _ := os.Open(file)       // ignoring error for brevity's sake
+mime, rerr := mimetype.DetectReader(reader)
+fmt.Println(mime, rerr)
+// Output: application/pdf nil
 
-// Output: application/pdf application/pdf application/pdf
-// <nil> <nil>
+mime := mimetype.Detect(data)
+fmt.Println(mime)
+// Output: application/pdf
 ```
 
 ### Check

README.md

@@ -6,7 +6,7 @@
   A package for detecting MIME types and extensions based on magic numbers
 </h4>
 <h6 align="center">
-  No bindings, thread safe and completely written in go
+  No C bindings, zero dependencies and thread safe
 </h6>
 
 <p align="center">

example_mimetype_test.go

@@ -17,18 +17,24 @@ import (
 //  mimetype.DetectFile(string) (*MIME, error)
 func Example_detect() {
 	file := "testdata/pdf.pdf"
-	reader, _ := os.Open(file)       // ignoring error for brevity's sake
+
+	// Detect the MIME type of a file stored as a byte slice.
 	data, _ := ioutil.ReadFile(file) // ignoring error for brevity's sake
+	mime := mimetype.Detect(data)
+	fmt.Println(mime)
 
-	dmime := mimetype.Detect(data)
-	rmime, rerr := mimetype.DetectReader(reader)
-	fmime, ferr := mimetype.DetectFile(file)
+	// Detect the MIME type of a reader.
+	reader, _ := os.Open(file) // ignoring error for brevity's sake
+	mime, rerr := mimetype.DetectReader(reader)
+	fmt.Println(mime, rerr)
 
-	fmt.Println(dmime, rmime, fmime)
-	fmt.Println(rerr, ferr)
+	// Detect the MIME type of a file.
+	mime, ferr := mimetype.DetectFile(file)
+	fmt.Println(mime, ferr)
 
-	// Output: application/pdf application/pdf application/pdf
-	// <nil> <nil>
+	// Output: application/pdf
+	// application/pdf <nil>
+	// application/pdf <nil>
 }
 
 // To check if some bytes/reader/file has a specific MIME type, first perform

mimetype.go

@@ -16,8 +16,8 @@ import (
 
 // Detect returns the MIME type found from the provided byte slice.
 //
-// Failure to identify the format results in application/octet-stream
-// being returned.
+// The result is always a valid MIME type, with application/octet-stream
+// returned when identification failed.
 func Detect(in []byte) (mime *MIME) {
 	if len(in) == 0 {
 		return newMIME("inode/x-empty", "", matchers.True)

tree.go

@@ -4,7 +4,7 @@ import "github.com/gabriel-vasile/mimetype/internal/matchers"
 
 // root is a matcher which passes for any slice of bytes.
 // When a matcher passes the check, the children matchers
-// are tried in order to find a more accurate mime type.
+// are tried in order to find a more accurate MIME type.
 var root = newMIME("application/octet-stream", "", matchers.True,
 	sevenZ, zip, pdf, ole, ps, psd, ogg, png, jpg, jp2, jpx, jpm, gif, webp,
 	exe, elf, ar, tar, xar, bz2, fits, tiff, bmp, ico, mp3, flac, midi, ape,