doc: improve fs.truncate functions' documentation

The default value of the `len` parameter is zero and it is included in
the documenetation.

This patch also has examples of how `ftruncate` can be used.

PR-URL: #7648
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>

Author: thefourtheye

doc/api/fs.md

@@ -739,19 +739,60 @@ added: v0.8.6
 -->
 
 * `fd` {Integer}
-* `len` {Integer}
+* `len` {Integer} default = `0`
 * `callback` {Function}
 
 Asynchronous ftruncate(2). No arguments other than a possible exception are
 given to the completion callback.
 
+If the file referred to by the file descriptor was larger than `len` bytes, only
+the first `len` bytes will be retained in the file.
+
+For example, the following program retains only the first four bytes of the file
+
+```js
+console.log(fs.readFileSync('temp.txt', 'utf8'));
+  // prints Node.js
+
+// get the file descriptor of the file to be truncated
+const fd = fs.openSync('temp.txt', 'r+');
+
+// truncate the file to first four bytes
+fs.ftruncate(fd, 4, (err) => {
+  assert.ifError(err);
+  console.log(fs.readFileSync('temp.txt', 'utf8'));
+});
+  // prints Node
+```
+
+If the file previously was shorter than `len` bytes, it is extended, and the
+extended part is filled with null bytes ('\0'). For example,
+
+```js
+console.log(fs.readFileSync('temp.txt', 'utf-8'));
+  // prints Node.js
+
+// get the file descriptor of the file to be truncated
+const fd = fs.openSync('temp.txt', 'r+');
+
+// truncate the file to 10 bytes, whereas the actual size is 7 bytes
+fs.ftruncate(fd, 10, (err) => {
+  assert.ifError(!err);
+  console.log(fs.readFileSync('temp.txt'));
+});
+  // prints <Buffer 4e 6f 64 65 2e 6a 73 00 00 00>
+  // ('Node.js\0\0\0' in UTF8)
+```
+
+The last three bytes are null bytes ('\0'), to compensate the over-truncation.
+
 ## fs.ftruncateSync(fd, len)
 <!-- YAML
 added: v0.8.6
 -->
 
 * `fd` {Integer}
-* `len` {Integer}
+* `len` {Integer} default = `0`
 
 Synchronous ftruncate(2). Returns `undefined`.
 
@@ -1368,7 +1409,7 @@ added: v0.8.6
 -->
 
 * `path` {String | Buffer}
-* `len` {Integer}
+* `len` {Integer} default = `0`
 * `callback` {Function}
 
 Asynchronous truncate(2). No arguments other than a possible exception are
@@ -1381,9 +1422,10 @@ added: v0.8.6
 -->
 
 * `path` {String | Buffer}
-* `len` {Integer}
+* `len` {Integer} default = `0`
 
-Synchronous truncate(2). Returns `undefined`.
+Synchronous truncate(2). Returns `undefined`. A file descriptor can also be
+passed as the first argument. In this case, `fs.ftruncateSync()` is called.
 
 ## fs.unlink(path, callback)
 <!-- YAML