From 363df219e01f7d7ffed8c99930054c9938cecc31 Mon Sep 17 00:00:00 2001
From: Janice Niemeir <Janice.guerrero@gmail.com>
Date: Tue, 21 Aug 2018 17:17:59 -0700
Subject: [PATCH] Docs: Update lastRun() documentation

---
 docs/api/last-run.md | 83 ++++++++++++++++++++++++++++++++++++++++++++
 docs/api/lastRun.md  | 43 -----------------------
 2 files changed, 83 insertions(+), 43 deletions(-)
 create mode 100644 docs/api/last-run.md
 delete mode 100644 docs/api/lastRun.md

diff --git a/docs/api/last-run.md b/docs/api/last-run.md
new file mode 100644
index 000000000..c7c2269cc
--- /dev/null
+++ b/docs/api/last-run.md
@@ -0,0 +1,83 @@
+<!-- front-matter
+id: api-lastrun
+title: lastRun()
+hide_title: true
+sidebar_label: lastRun()
+-->
+
+# lastRun()
+
+Retrieves the last time a task was successfully completed during the current running process. Most useful on subsequent task runs while a watcher is running.
+
+When combined with `src()`, enables incremental builds to speed up your execution times by skipping files that haven't changed since the last successful task completion.
+
+## Usage
+
+```js
+const { src, dest, lastRun, watch } = require('gulp');
+const imagemin = require('gulp-imagemin');
+
+function images() {
+  return src('src/images/**/*.jpg', { since: lastRun(images) })
+    .pipe(imagemin())
+    .pipe(dest('build/img/'));
+}
+
+function watch() {
+  watch('src/images/**/*.jpg', images);
+}
+
+exports.watch = watch;
+```
+
+
+## Signature
+
+```js
+lastRun(task, [precision])
+```
+
+### Parameters
+
+| parameter | type | note |
+|:--------------:|:------:|-------|
+| task <br> **(required)** | function <br> string | The task function or the string alias of a registered task. |
+| precision | number | Default: `1000` on Node v0.10, `0` on Node v0.12+. Detailed in Timestamp precision][timestamp-precision-section] section below. |
+
+### Returns
+
+A timestamp (in milliseconds), matching the last completion time of the task. If the task has not been run or has failed, returns `undefined`.
+
+To avoid an invalid state being cached, the returned value will be `undefined` if a task errors.
+
+### Errors
+
+When called with a value other than a string or function, throws an error with the message, "Only functions can check lastRun".
+
+When called on a non-extensible function and Node is missing WeakMap, throws an error with the message, "Only extensible functions can check lastRun".
+
+## Timestamp precision
+
+While there are sensible defaults for the precision of timestamps, they can be rounded using the `precision` parameter. Useful if your file system or Node version has a lossy precision on file time attributes.
+
+* `lastRun(someTask)` returns 1426000001111
+* `lastRun(someTask, 100)` returns 1426000001100
+* `lastRun(someTask, 1000)` returns 1426000001000
+
+A file's [mtime stat][fs-stats-concepts] precision may vary depending on the node version and/or the file system used:
+
+
+| platform | precision |
+|:-----------:|:------------:|
+| Node v0.10 | 1000ms |
+| Node v0.12+ | 1ms |
+| FAT32 file system | 2000ms |
+| HFS+ or Ext3 file systems | 1000ms |
+| NTFS using Node v0.10 | 1s |
+| NTFS using Node 0.12+ | 100ms |
+| Ext4 using Node v0.10 | 1000ms |
+| Ext4 using Node 0.12+ | 1ms |
+
+
+[timestamp-precision-section]: #timestamp-precision
+[fs-stats-concepts]: concepts.md#file-system-stats
diff --git a/docs/api/lastRun.md b/docs/api/lastRun.md
deleted file mode 100644
index 2be1e668f..000000000
--- a/docs/api/lastRun.md
+++ /dev/null
@@ -1,43 +0,0 @@
-<!-- front-matter
-id: api-lastRun
-title: lastRun()
-hide_title: true
-sidebar_label: lastRun()
--->
-
-# `gulp.lastRun(taskName, [timeResolution])`
-
-Returns the timestamp of the last time the task ran successfully. The time
-will be the time the task started. Returns `undefined` if the task has
-not run yet.
-
-## taskName
-
-Type: `String`
-
-The name of the registered task or of a function.
-
-## timeResolution
-
-Type: `Number`.
-
-Default: `1000` on node v0.10, `0` on node v0.12 (and iojs v1.5).
-
-Set the time resolution of the returned timestamps. Assuming
-the task named "someTask" ran at `1426000004321`:
-
-- `gulp.lastRun('someTask', 1000)` would return `1426000004000`.
-- `gulp.lastRun('someTask', 100)` would return `1426000004300`.
-
-`timeResolution` allows you to compare a run time to a file [mtime stat][fs stats]
-attribute. This attribute time resolution may vary depending of the node version
-and the file system used:
-
-- on node v0.10, a file [mtime stat][fs stats] time resolution of any files will be 1s at best;
-- on node v0.12 and iojs v1.5, 1ms at best;
-- for files on FAT32, the mtime time resolution is 2s;
-- on HFS+ and Ext3, 1s;
-- on NTFS, 1s on node v0.10, 100ms on node 0.12;
-- on Ext4, 1s on node v0.10, 1ms on node 0.12.
-
-[fs stats]: https://nodejs.org/api/fs.html#fs_class_fs_stats