From 1d7a0ea99e97dc7ebef866d00e23c7088ae91764 Mon Sep 17 00:00:00 2001
From: Lovell Fuller <github@lovell.info>
Date: Sat, 9 Dec 2017 13:14:23 +0000
Subject: [PATCH] Changelog and doc refresh for #915

---
 docs/api-input.md | 16 ++++++++--------
 docs/changelog.md |  4 ++++
 lib/input.js      | 31 +++++++++++++++----------------
 3 files changed, 27 insertions(+), 24 deletions(-)

diff --git a/docs/api-input.md b/docs/api-input.md
index cecf34b2..15e55513 100644
--- a/docs/api-input.md
+++ b/docs/api-input.md
@@ -4,6 +4,7 @@
 
 -   [clone](#clone)
 -   [metadata](#metadata)
+-   [stats](#stats)
 -   [limitInputPixels](#limitinputpixels)
 -   [sequentialRead](#sequentialread)
 
@@ -69,10 +70,10 @@ Returns **([Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Ref
 
 ## stats
 
-Access to pixel-derived image statistics for every channel in the image
-A Promises/A+ promise is returned when `callback` is not provided.
+Access to pixel-derived image statistics for every channel in the image.
+A Promise is returned when `callback` is not provided.
 
--   `channels`: Array of channel statistics for each channel in the image. Each channel statistic contains 
+-   `channels`: Array of channel statistics for each channel in the image. Each channel statistic contains
     -   `min` (minimum value in the channel)
     -   `max` (maximum value in the channel)
     -   `sum` (sum of all values in a channel)
@@ -87,7 +88,7 @@ A Promises/A+ promise is returned when `callback` is not provided.
 
 **Parameters**
 
--   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** called with the arguments `(err, metadata)`
+-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** called with the arguments `(err, stats)`
 
 **Examples**
 
@@ -96,12 +97,11 @@ const image = sharp(inputJpg);
 image
   .stats()
   .then(function(stats) {
-    // stats contains the channel-wise statistics array and the isOpaque value
-  })
+     // stats contains the channel-wise statistics array and the isOpaque value
+  });
 ```
 
-Returns **([Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)> | Sharp)** 
-
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** 
 
 ## limitInputPixels
 
diff --git a/docs/changelog.md b/docs/changelog.md
index 1f576c55..de7fee77 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -14,6 +14,10 @@ Requires libvips v8.6.0.
   [#872](https://github.com/lovell/sharp/issues/872)
   [@wmertens](https://github.com/wmertens)
 
+* Add stats feature for pixel-derived image statistics.
+  [#915](https://github.com/lovell/sharp/pull/915)
+  [@rnanwani](https://github.com/rnanwani)
+
 * Add failOnError option to fail-fast on bad input image data.
   [#976](https://github.com/lovell/sharp/pull/976)
   [@mceachen](https://github.com/mceachen)
diff --git a/lib/input.js b/lib/input.js
index f9ec8b5b..08e4aeb6 100644
--- a/lib/input.js
+++ b/lib/input.js
@@ -239,20 +239,20 @@ function metadata (callback) {
 }
 
 /**
- * Access to pixel-derived image statistics for every channel in the image
- * A Promise/A+ promise is returned when `callback` is not provided.
+ * Access to pixel-derived image statistics for every channel in the image.
+ * A Promise is returned when `callback` is not provided.
  *
- * -   `channels`: Array of channel statistics for each channel in the image. Each channel statistic contains
- *  -   `min` (minimum value in the channel)
- *  -   `max` (maximum value in the channel)
- *  -   `sum` (sum of all values in a channel)
- *  -   `squaresSum` (sum of squared values in a channel)
- *  -   `mean` (mean of the values in a channel)
- *  -   `stdev` (standard deviation for the values in a channel)
- *  -   `minX` (x-coordinate of one of the pixel where the minimum lies)
- *  -   `minY` (y-coordinate of one of the pixel where the minimum lies)
- *  -   `maxX` (x-coordinate of one of the pixel where the maximum lies)
- *  -   `maxY` (y-coordinate of one of the pixel where the maximum lies)
+ * - `channels`: Array of channel statistics for each channel in the image. Each channel statistic contains
+ *     - `min` (minimum value in the channel)
+ *     - `max` (maximum value in the channel)
+ *     - `sum` (sum of all values in a channel)
+ *     - `squaresSum` (sum of squared values in a channel)
+ *     - `mean` (mean of the values in a channel)
+ *     - `stdev` (standard deviation for the values in a channel)
+ *     - `minX` (x-coordinate of one of the pixel where the minimum lies)
+ *     - `minY` (y-coordinate of one of the pixel where the minimum lies)
+ *     - `maxX` (x-coordinate of one of the pixel where the maximum lies)
+ *     - `maxY` (y-coordinate of one of the pixel where the maximum lies)
  * - `isOpaque`: Value to identify if the image is opaque or transparent, based on the presence and use of alpha channel
  *
  * @example
@@ -261,11 +261,10 @@ function metadata (callback) {
  *   .stats()
  *   .then(function(stats) {
  *      // stats contains the channel-wise statistics array and the isOpaque value
- *   })
- *
+ *   });
  *
  * @param {Function} [callback] - called with the arguments `(err, stats)`
- * @returns {Promise<Object>|Sharp}
+ * @returns {Promise<Object>}
  */
 function stats (callback) {
   const that = this;