docs(touch): clarify docs for touch() command

nfischer · nfischer · commit 05fc05d37e42 · 2022-02-13T17:21:58.000-08:00
No change to logic. This expands on the `touch()` command documentation
to make it more obvious how to use multiple options, long options, etc.
This also renames a variable in a test case to make the usage more
obvious.
diff --git a/README.md b/README.md
@@ -681,17 +681,18 @@ Available options:
 + `-a`: Change only the access time
 + `-c`: Do not create any files
 + `-m`: Change only the modification time
-+ `{'-d': someDate}`, `{date: someDate}`: Use `someDate` (instance of
-  `Date`) instead of current time
++ `{'-d': someDate}`, `{date: someDate}`: Use a `Date` instance (ex. `someDate`)
+  instead of current time
 + `{'-r': file}`, `{reference: file}`: Use `file`'s times instead of current
-   time
+  time
 
 Examples:
 
 ```javascript
 touch('source.js');
 touch('-c', 'path/to/file.js');
 touch({ '-r': 'referenceFile.txt' }, 'path/to/file.js');
+touch({ '-d': new Date('December 17, 1995 03:24:00'), '-m': true }, 'path/to/file.js');
 touch({ date: new Date('December 17, 1995 03:24:00') }, 'path/to/file.js');
 ```
 
diff --git a/src/touch.js b/src/touch.js
@@ -20,17 +20,18 @@ common.register('touch', _touch, {
 //@ + `-a`: Change only the access time
 //@ + `-c`: Do not create any files
 //@ + `-m`: Change only the modification time
-//@ + `{'-d': someDate}`, `{date: someDate}`: Use `someDate` (instance of
-//@   `Date`) instead of current time
+//@ + `{'-d': someDate}`, `{date: someDate}`: Use a `Date` instance (ex. `someDate`)
+//@   instead of current time
 //@ + `{'-r': file}`, `{reference: file}`: Use `file`'s times instead of current
-//@    time
+//@   time
 //@
 //@ Examples:
 //@
 //@ ```javascript
 //@ touch('source.js');
 //@ touch('-c', 'path/to/file.js');
 //@ touch({ '-r': 'referenceFile.txt' }, 'path/to/file.js');
+//@ touch({ '-d': new Date('December 17, 1995 03:24:00'), '-m': true }, 'path/to/file.js');
 //@ touch({ date: new Date('December 17, 1995 03:24:00') }, 'path/to/file.js');
 //@ ```
 //@
diff --git a/test/touch.js b/test/touch.js
@@ -129,14 +129,14 @@ test('accepts -d flag', t => {
   t.is(common.statFollowLinks(testFile).atime.getTime(), date.getTime());
 });
 
-test('accepts long option (date)', t => {
+test('accepts long option (--date)', t => {
   const testFile = tmpFile(t);
-  const date = new Date('December 17, 1995 03:24:00');
-  const result = shell.touch({ date }, testFile);
+  const someDate = new Date('December 17, 1995 03:24:00');
+  const result = shell.touch({ date: someDate }, testFile);
   t.is(result.code, 0);
   // Compare getTime(), because Date can't be compared with triple-equals.
-  t.is(common.statFollowLinks(testFile).mtime.getTime(), date.getTime());
-  t.is(common.statFollowLinks(testFile).atime.getTime(), date.getTime());
+  t.is(common.statFollowLinks(testFile).mtime.getTime(), someDate.getTime());
+  t.is(common.statFollowLinks(testFile).atime.getTime(), someDate.getTime());
 });
 
 test('sets mtime and atime by default', t => {
