Improve docs

mime.go

@@ -1,11 +1,10 @@
 // Package mimetype uses magic number signatures to detect the MIME type of a file.
 //
 // mimetype stores the list of MIME types in a tree structure with
-// "application/octet-stream" at the root of the hierarchy. When the detection
-// fails to find any result for an input, the MIME type "application/octet-stream"
-// is returned. The hierarchy approach minimises the number of checks that need
-// to be done on the input  and allows for more precise results once the base
-// type of file has been identified.
+// "application/octet-stream" at the root of the hierarchy. The hierarchy
+// approach minimizes the number of checks that need to be done on the input
+// and allows for more precise results once the base type of file has been
+// identified.
 package mimetype
 
 import (
@@ -15,7 +14,9 @@ import (
 	"github.com/gabriel-vasile/mimetype/internal/matchers"
 )
 
-// Detect returns the MIME type of the provided byte slice.
+// Detect returns the MIME type found from the provided byte slice.
+// Failure to identify the format results in application/octet-stream
+// being returned.
 func Detect(in []byte) (mime *MIME) {
 	if len(in) == 0 {
 		return newMIME("inode/x-empty", "", matchers.True)
@@ -25,6 +26,8 @@ func Detect(in []byte) (mime *MIME) {
 }
 
 // DetectReader returns the MIME type of the provided reader.
+// The result is always a valid MIME type, with application/octet-stream
+// returned when identification failed with or without an error.
 func DetectReader(r io.Reader) (mime *MIME, err error) {
 	in := make([]byte, matchers.ReadLimit)
 	n, err := r.Read(in)
@@ -37,6 +40,8 @@ func DetectReader(r io.Reader) (mime *MIME, err error) {
 }
 
 // DetectFile returns the MIME type of the provided file.
+// The result is always a valid MIME type, with application/octet-stream
+// returned when identification failed with or without an error.
 func DetectFile(file string) (mime *MIME, err error) {
 	f, err := os.Open(file)
 	if err != nil {