chore: Final JSDoc updates & changelog fixes

metalsmith · Jun 10, 2022 · e988eaa · e988eaa
1 parent c44edb2
commit e988eaa
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 26 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,10 +12,8 @@ This document follows the guidelines of [Keep A Changelog](http://keepachangelog
 
 - [#354] Added `Metalsmith#env` method. Supports passing `DEBUG` and `DEBUG_LOG` amongst others. Sets `CLI: true` when run from the metalsmith CLI. [`b42df8c`](https://github.com/metalsmith/metalsmith/commit/b42df8c), [`446c676`](https://github.com/metalsmith/metalsmith/commit/446c676), [`33d936b`](https://github.com/metalsmith/metalsmith/commit/33d936b), [`4c483a3`](https://github.com/metalsmith/metalsmith/commit/4c483a3)
 - [#356] Added `Metalsmith#debug` method for creating plugin debuggers
-- [#362] Upgraded all generator-based methods (`Metalsmith#read`,`Metalsmith#readFile`,`Metalsmith#write`,`Metalsmith#writeFile` and `Metalsmith#run`) to dual callback-/ promise-based methods [`16a91c5`](https://github.com/metalsmith/metalsmith/commit/16a91c5), [`faf6ab6`](https://github.com/metalsmith/metalsmith/commit/faf6ab6), [`6cb6229`](https://github.com/metalsmith/metalsmith/commit/6cb6229)
+- [#362] Upgraded all generator-based methods (`Metalsmith#read`,`Metalsmith#readFile`,`Metalsmith#write`,`Metalsmith#writeFile`, `Metalsmith#run` and `Metalsmith#process`) to dual callback-/ promise-based methods [`16a91c5`](https://github.com/metalsmith/metalsmith/commit/16a91c5), [`faf6ab6`](https://github.com/metalsmith/metalsmith/commit/faf6ab6), [`6cb6229`](https://github.com/metalsmith/metalsmith/commit/6cb6229)
 - Added org migration notification to postinstall script to encourage users to upgrade [`3a11a24`](https://github.com/metalsmith/metalsmith/commit/3a11a24)
-- [#355] Proper path resolution for edge-cases using CLI, running metalsmith from outside or subfolder of `metalsmith.directory()`[`5d75539`](https://github.com/metalsmith/metalsmith/commit/5d75539)
-- [#247] Calling `Metalsmith#metadata` no longer clones the object passed to it, overwriting the previous metadata, but merges it into existing metadata.
 
 ### Removed
 
@@ -30,18 +28,17 @@ This document follows the guidelines of [Keep A Changelog](http://keepachangelog
 ### Updated
 
 - Restructured and updated `README.md` [`0da0c4d`](https://github.com/metalsmith/metalsmith/commit/0da0c4d)
+- [#247] Calling `Metalsmith#metadata` no longer clones the object passed to it, overwriting the previous metadata, but merges it into existing metadata.
 
 [#362]: https://github.com/metalsmith/metalsmith/issues/362
 [#354]: https://github.com/metalsmith/metalsmith/issues/354
 [#355]: https://github.com/metalsmith/metalsmith/issues/355
 [#356]: https://github.com/metalsmith/metalsmith/issues/356
 [#247]: https://github.com/metalsmith/metalsmith/issues/247
 
-### Updated
+### Fixed
 
-- **Dependencies:** [`774a164`](https://github.com/metalsmith/metalsmith/commit/774a164)
-  - `micromatch`: 4.0.4 ▶︎ 4.0.5
-- Updated README.md
+- [#355] Proper path resolution for edge-cases using CLI, running metalsmith from outside or subfolder of `metalsmith.directory()`[`5d75539`](https://github.com/metalsmith/metalsmith/commit/5d75539)
 
 ## [2.4.3] - 2022-05-16
 

diff --git a/lib/index.js b/lib/index.js
@@ -151,7 +151,7 @@ Metalsmith.prototype.use = function (plugin) {
 /**
  * Get or set the working `directory`.
  *
- * @param {Object} [directory]
+ * @param {string} [directory]
  * @return {string|Metalsmith}
  *
  * @example
@@ -256,15 +256,18 @@ Metalsmith.prototype.clean = function (clean) {
   return this
 }
 
+/** @typedef {Object} GrayMatterOptions */
+
 /**
- * Optionally turn off frontmatter parsing.
+ * Optionally turn off frontmatter parsing or pass a [gray-matter options object](https://github.com/jonschlinkert/gray-matter/tree/4.0.2#option)
  *
- * @param {boolean} [frontmatter]
+ * @param {boolean|GrayMatterOptions} [frontmatter]
  * @return {boolean|Metalsmith}
  *
  * @example
  * metalsmith.frontmatter(false)  // turn off front-matter parsing
  * metalsmith.frontmatter()       // returns false
+ * metalsmith.frontmatter({ excerpt: true })
  */
 
 Metalsmith.prototype.frontmatter = function (frontmatter) {
@@ -285,7 +288,7 @@ Metalsmith.prototype.frontmatter = function (frontmatter) {
  * @return {Metalsmith|string[]}
  *
  * @example
- * metalsmith.ignore()
+ * metalsmith.ignore()                      // return a list of ignored file paths
  * metalsmith.ignore('layouts')             // ignore the layouts directory
  * metalsmith.ignore(['.*', 'data.json'])   // ignore dot files & a data file
  */
@@ -314,8 +317,8 @@ Metalsmith.prototype.path = function (...paths) {
  * If `input` is not specified, patterns are matched against `Object.keys(files)`
  *
  * @param {string|string[]} patterns - one or more glob patterns
- * @param {import('micromatch').Options} options - [micromatch options](https://github.com/micromatch/micromatch#options), except `format`
  * @param {string[]} [input] array of strings to match against
+ * @param {import('micromatch').Options} options - [micromatch options](https://github.com/micromatch/micromatch#options), except `format`
  * @returns {string[]} An array of matching file paths
  */
 
@@ -329,6 +332,7 @@ Metalsmith.prototype.match = function (patterns, input, options) {
  * Get or set one or multiple metalsmith environment variables. Metalsmith env vars are case-insensitive.
  * @param {string|Object} [vars] name of the environment variable, or an object with `{ name: 'value' }` pairs
  * @param {string|number|boolean} [value] value of the environment variable
+ * @returns {string|number|boolean|Object|Metalsmith}
  * @example
  * // pass all Node env variables
  * metalsmith.env(process.env)
@@ -418,7 +422,7 @@ Metalsmith.prototype.build = function (callback) {
       })
     })
 
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   if (isFunction(callback)) {
     result.then((files) => callback(null, files), callback)
   } else {
@@ -431,10 +435,10 @@ Metalsmith.prototype.build = function (callback) {
  *
  * @method Metalsmith#process
  * @param {BuildCallback} [callback]
- * @return {Files}
+ * @return {Promise<Files>|void}
  *
  * @example
- * metalsmith.process(err => {
+ * metalsmith.process((err, files) => {
  *   if (err) throw err
  *   console.log('Success')
  *   console.log(this.metadata())
@@ -446,7 +450,7 @@ Metalsmith.prototype.process = function (callback) {
     return this.run(files, this.plugins)
   })
 
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   if (callback) {
     result.then((files) => callback(null, files), callback)
   } else {
@@ -461,7 +465,7 @@ Metalsmith.prototype.process = function (callback) {
  * @package
  * @param {Files} files
  * @param {Plugin[]} plugins
- * @return {Object}
+ * @return {Promise<Files>|void}
  */
 
 Metalsmith.prototype.run = function (files, plugins, callback) {
@@ -473,7 +477,7 @@ Metalsmith.prototype.run = function (files, plugins, callback) {
     this.debug.enable(debugValue)
   }
 
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   const last = arguments[arguments.length - 1]
   callback = isFunction(last) ? last : undefined
   plugins = Array.isArray(plugins) ? plugins : this.plugins
@@ -490,7 +494,7 @@ Metalsmith.prototype.run = function (files, plugins, callback) {
     })
   })
 
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   if (callback) {
     result.then((files) => callback(null, files, this), callback)
   } else {
@@ -505,11 +509,11 @@ Metalsmith.prototype.run = function (files, plugins, callback) {
  * @method Metalsmith#read
  * @package
  * @param {string} [dir]
- * @return {Object}
+ * @return {Promise<Files>|void}
  */
 
 Metalsmith.prototype.read = function (dir, callback) {
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   if (isFunction(dir) || !arguments.length) {
     callback = dir
     dir = this.source()
@@ -528,7 +532,7 @@ Metalsmith.prototype.read = function (dir, callback) {
     })
   })
 
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   if (callback) {
     result.then((files) => callback(null, files), callback)
   } else {
@@ -543,7 +547,7 @@ Metalsmith.prototype.read = function (dir, callback) {
  * @method Metalsmith#readFile
  * @package
  * @param {string} file
- * @returns {File}
+ * @returns {Promise<File>|void}
  */
 
 Metalsmith.prototype.readFile = function (file, callback) {
@@ -603,10 +607,11 @@ Metalsmith.prototype.readFile = function (file, callback) {
  * @package
  * @param {Files} files
  * @param {string} [dir]
+ * @returns {Promise<null>|void}
  */
 
 Metalsmith.prototype.write = function (files, dir, callback) {
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   const last = arguments[arguments.length - 1]
   callback = isFunction(last) ? last : undefined
   dir = dir && !isFunction(dir) ? dir : this.destination()
@@ -623,7 +628,7 @@ Metalsmith.prototype.write = function (files, dir, callback) {
     concurrency
   )
 
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   if (callback) {
     operation.then(() => callback(null), callback)
   } else {
@@ -639,6 +644,7 @@ Metalsmith.prototype.write = function (files, dir, callback) {
  * @package
  * @param {string} file
  * @param {File} data
+ * @returns {Promise<void>|void}
  */
 
 Metalsmith.prototype.writeFile = function (file, data, callback) {
@@ -651,7 +657,7 @@ Metalsmith.prototype.writeFile = function (file, data, callback) {
     return Promise.reject(e)
   })
 
-  /** block required for Metalsmith 2.x callback-flow compat */
+  /* block required for Metalsmith 2.x callback-flow compat */
   if (callback) {
     result.then(callback, callback)
   } else {