doc: clarify fs.mkdtemp prefix argument

Per: #6142

Clarify the prefix argument.

Fixes: #6142
PR-URL: #6800
Reviewed-By: Ben Noordhuis <[email protected]>
Reviewed-By: Roman Klauke <[email protected]>

Author: jasnell

doc/api/fs.md

@@ -900,6 +900,37 @@ fs.mkdtemp('/tmp/foo-', (err, folder) => {
 });
 ```
 
+*Note*: The `fs.mkdtemp()` method will append the six randomly selected
+characters directly to the `prefix` string. For instance, given a directory
+`/tmp`, if the intention is to create a temporary directory *within* `/tmp`,
+the `prefix` *must* end with a trailing platform-specific path separator
+(`require('path').sep`).
+
+```js
+// The parent directory for the new temporary directory
+const tmpDir = '/tmp';
+
+// This method is *INCORRECT*:
+fs.mkdtemp(tmpDir, (err, folder) => {
+  if (err) throw err;
+  console.log(folder);
+    // Will print something similar to `/tmp-abc123`.
+    // Note that a new temporary directory is created
+    // at the file system root rather than *within*
+    // the /tmp directory.
+});
+
+// This method is *CORRECT*:
+const path = require('path');
+fs.mkdtemp(tmpDir + path.sep, (err, folder) => {
+  if (err) throw err;
+  console.log(folder);
+    // Will print something similar to `/tmp/abc123`.
+    // A new temporary directory is created within
+    // the /tmp directory.
+});
+```
+
 ## fs.mkdtempSync(template)
 <!-- YAML
 added: v5.10.0