From e4a809e38ccf6b4fdfa457fecf816b4f9f0dbc40 Mon Sep 17 00:00:00 2001
From: Sindre Sorhus <sindresorhus@gmail.com>
Date: Mon, 3 Jan 2022 14:36:03 +0100
Subject: [PATCH] Improve docs for `fileTypeFromBlob`

Fixes #521
---
 browser.d.ts |  8 ++++++--
 core.d.ts    |  7 ++++---
 readme.md    | 39 +++++++++++++++++++++++++++------------
 3 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/browser.d.ts b/browser.d.ts
index 73fa829e..551a13dd 100644
--- a/browser.d.ts
+++ b/browser.d.ts
@@ -1,8 +1,9 @@
 import {FileTypeResult} from './core.js';
 
 /**
-Determine file type from a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
+Detect the file type of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
 
+@example
 ```
 import {fileTypeFromStream} from 'file-type';
 
@@ -18,8 +19,11 @@ console.log(fileType);
 export declare function fileTypeFromStream(stream: ReadableStream): Promise<FileTypeResult | undefined>;
 
 /**
-Determine file type from a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+Detect the file type of a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
 
+__Note:__ This method is only available in the browser.
+
+@example
 ```
 import {fileTypeFromBlob} from 'file-type';
 
diff --git a/core.d.ts b/core.d.ts
index b437458a..b74f8cc1 100644
--- a/core.d.ts
+++ b/core.d.ts
@@ -323,8 +323,12 @@ This method is used internally, but can also be used for a special "tokenizer" r
 
 A tokenizer propagates the internal read functions, allowing alternative transport mechanisms, to access files, to be implemented and used.
 
+@param tokenizer - File source implementing the tokenizer interface.
+@returns The detected file type and MIME type, or `undefined` when there is no match.
+
 An example is [`@tokenizer/http`](https://github.com/Borewit/tokenizer-http), which requests data using [HTTP-range-requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests). A difference with a conventional stream and the [*tokenizer*](https://github.com/Borewit/strtok3#tokenizer), is that it is able to *ignore* (seek, fast-forward) in the stream. For example, you may only need and read the first 6 bytes, and the last 128 bytes, which may be an advantage in case reading the entire file would take longer.
 
+@example
 ```
 import {makeTokenizer} from '@tokenizer/http';
 import {fileTypeFromTokenizer} from 'file-type';
@@ -337,9 +341,6 @@ const fileType = await fileTypeFromTokenizer(httpTokenizer);
 console.log(fileType);
 //=> {ext: 'mp3', mime: 'audio/mpeg'}
 ```
-
-@param tokenizer - File source implementing the tokenizer interface.
-@returns The detected file type and MIME type, or `undefined` when there is no match.
 */
 export function fileTypeFromTokenizer(tokenizer: ITokenizer): Promise<FileTypeResult | undefined>;
 
diff --git a/readme.md b/readme.md
index b92c75a3..fa7e6057 100644
--- a/readme.md
+++ b/readme.md
@@ -129,18 +129,6 @@ console.log(fileType);
 //=> {ext: 'jpg', mime: 'image/jpeg'}
 ```
 
-```js
-import {fileTypeFromBlob} from 'file-type';
-
-const blob = new Blob(['<?xml version="1.0" encoding="ISO-8859-1" ?>'], {
-	type: 'plain/text',
-	endings: 'native'
-});
-
-console.log(await fileTypeFromBlob(blob));
-//=> {ext: 'txt', mime: 'plain/text'}
-```
-
 ## API
 
 ### fileTypeFromBuffer(buffer)
@@ -202,6 +190,33 @@ Type: [`stream.Readable`](https://nodejs.org/api/stream.html#stream_class_stream
 
 A readable stream representing file data.
 
+### fileTypeFromBlob(blob)
+
+Detect the file type of a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+
+**Note:** This method is only available in the browser.
+
+The file type is detected by checking the [magic number](https://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files) of the buffer.
+
+Returns a `Promise` for an object with the detected file type and MIME type:
+
+- `ext` - One of the [supported file types](#supported-file-types)
+- `mime` - The [MIME type](https://en.wikipedia.org/wiki/Internet_media_type)
+
+Or `undefined` when there is no match.
+
+```js
+import {fileTypeFromBlob} from 'file-type';
+
+const blob = new Blob(['<?xml version="1.0" encoding="ISO-8859-1" ?>'], {
+	type: 'plain/text',
+	endings: 'native'
+});
+
+console.log(await fileTypeFromBlob(blob));
+//=> {ext: 'txt', mime: 'plain/text'}
+```
+
 ### fileTypeFromTokenizer(tokenizer)
 
 Detect the file type from an `ITokenizer` source.