Docs: changelog entry and example for #2527

lib/constructor.js

@@ -104,6 +104,21 @@ const debuglog = util.debuglog('sharp');
  * });
  * await image.toFile('my-two-pixels.png');
  *
+ * @example
+ * // Generate RGB Gaussian noise
+ * await sharp({
+ *   create: {
+ *     width: 300,
+ *     height: 200,
+ *     channels: 3,
+ *     noise: {
+ *       type: 'gaussian',
+ *       mean: 128,
+ *       sigma: 30
+ *     }
+ *  }
+ * }.toFile('noise.png');
+ *
  * @param {(Buffer|Uint8Array|Uint8ClampedArray|string)} [input] - if present, can be
  *  a Buffer / Uint8Array / Uint8ClampedArray containing JPEG, PNG, WebP, AVIF, GIF, SVG, TIFF or raw pixel image data, or
  *  a String containing the filesystem path to an JPEG, PNG, WebP, AVIF, GIF, SVG or TIFF image file.
@@ -130,6 +145,10 @@ const debuglog = util.debuglog('sharp');
  * @param {number} [options.create.height] - integral number of pixels high.
  * @param {number} [options.create.channels] - integral number of channels, either 3 (RGB) or 4 (RGBA).
  * @param {string|Object} [options.create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
+ * @param {Object} [options.create.noise] - describes a noise to be created.
+ * @param {string} [options.create.noise.type] - type of generated noise, currently only `gaussian` is supported.
+ * @param {number} [options.create.noise.mean] - mean of pixels in generated noise.
+ * @param {number} [options.create.noise.sigma] - standard deviation of pixels in generated noise.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */