docs: fix typos and adjust markdown formatting (#825)

Miscellaneous docs/markdown changes. No change to logic.

shell.js

@@ -11,7 +11,7 @@ var common = require('./src/common');
 //@
 //@ All commands run synchronously, unless otherwise stated.
 //@ All commands accept standard bash globbing characters (`*`, `?`, etc.),
-//@ compatible with the [node glob module](https://github.com/isaacs/node-glob).
+//@ compatible with the [node `glob` module](https://github.com/isaacs/node-glob).
 //@
 //@ For less-commonly used commands and features, please check out our [wiki
 //@ page](https://github.com/shelljs/shelljs/wiki).
@@ -27,7 +27,8 @@ require('./commands').forEach(function (command) {
 
 //@
 //@ ### exit(code)
-//@ Exits the current process with the given exit code.
+//@
+//@ Exits the current process with the given exit `code`.
 exports.exit = process.exit;
 
 //@include ./src/error
@@ -38,8 +39,9 @@ exports.ShellString = common.ShellString;
 
 //@
 //@ ### env['VAR_NAME']
+//@
 //@ Object containing environment variables (both getter and setter). Shortcut
-//@ to process.env.
+//@ to `process.env`.
 exports.env = process.env;
 
 //@
@@ -91,9 +93,9 @@ exports.config = common.config;
 //@ /* more commands... */
 //@ ```
 //@
-//@ If `true` the script will throw a Javascript error when any shell.js
+//@ If `true`, the script will throw a Javascript error when any shell.js
 //@ command encounters an error. Default is `false`. This is analogous to
-//@ Bash's `set -e`
+//@ Bash's `set -e`.
 
 //@
 //@ ### config.verbose
@@ -140,7 +142,7 @@ exports.config = common.config;
 //@ /* ... */
 //@ ```
 //@
-//@ Reset shell.config to the defaults:
+//@ Reset `shell.config` to the defaults:
 //@
 //@ ```javascript
 //@ {

src/cat.js

@@ -11,6 +11,7 @@ common.register('cat', _cat, {
 //@
 //@ ### cat([options,] file [, file ...])
 //@ ### cat([options,] file_array)
+//@
 //@ Available options:
 //@
 //@ + `-n`: number all output lines

src/cd.js

@@ -5,6 +5,7 @@ common.register('cd', _cd, {});
 
 //@
 //@ ### cd([dir])
+//@
 //@ Changes to directory `dir` for the duration of the script. Changes to home
 //@ directory if no argument is supplied.
 function _cd(options, dir) {

src/chmod.js

@@ -39,7 +39,7 @@ common.register('chmod', _chmod, {
 //@ Available options:
 //@
 //@ + `-v`: output a diagnostic for every file processed//@
-//@ + `-c`: like verbose but report only when a change is made//@
+//@ + `-c`: like verbose, but report only when a change is made//@
 //@ + `-R`: change files and directories recursively//@
 //@
 //@ Examples:
@@ -56,9 +56,9 @@ common.register('chmod', _chmod, {
 //@ This command tries to mimic the POSIX behavior as much as possible.
 //@ Notable exceptions:
 //@
-//@ + In symbolic modes, 'a-r' and '-r' are identical.  No consideration is
-//@   given to the umask.
-//@ + There is no "quiet" option since default behavior is to run silent.
+//@ + In symbolic modes, `a-r` and `-r` are identical.  No consideration is
+//@   given to the `umask`.
+//@ + There is no "quiet" option, since default behavior is to run silent.
 function _chmod(options, mode, filePattern) {
   if (!filePattern) {
     if (options.length > 0 && options.charAt(0) === '-') {

src/common.js

@@ -129,7 +129,7 @@ exports.error = error;
 //@ ```
 //@
 //@ Turns a regular string into a string-like object similar to what each
-//@ command returns. This has special methods, like `.to()` and `.toEnd()`
+//@ command returns. This has special methods, like `.to()` and `.toEnd()`.
 function ShellString(stdout, stderr, code) {
   var that;
   if (stdout instanceof Array) {

src/cp.js

@@ -186,11 +186,12 @@ function cpcheckcycle(sourceDir, srcFile) {
 //@
 //@ ### cp([options,] source [, source ...], dest)
 //@ ### cp([options,] source_array, dest)
+//@
 //@ Available options:
 //@
 //@ + `-f`: force (default behavior)
 //@ + `-n`: no-clobber
-//@ + `-u`: only copy if source is newer than dest
+//@ + `-u`: only copy if `source` is newer than `dest`
 //@ + `-r`, `-R`: recursive
 //@ + `-L`: follow symlinks
 //@ + `-P`: don't follow symlinks

src/dirs.js

@@ -44,7 +44,7 @@ function _actualDirStack() {
 //@
 //@ Arguments:
 //@
-//@ + `dir`: Makes the current working directory be the top of the stack, and then executes the equivalent of `cd dir`.
+//@ + `dir`: Sets the current working directory to the top of the stack, then executes the equivalent of `cd dir`.
 //@ + `+N`: Brings the Nth directory (counting from the left of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.
 //@ + `-N`: Brings the Nth directory (counting from the right of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.
 //@
@@ -56,7 +56,7 @@ function _actualDirStack() {
 //@ pushd('+1');   // Returns /usr /etc
 //@ ```
 //@
-//@ Save the current directory on the top of the directory stack and then cd to `dir`. With no arguments, pushd exchanges the top two directories. Returns an array of paths in the stack.
+//@ Save the current directory on the top of the directory stack and then `cd` to `dir`. With no arguments, `pushd` exchanges the top two directories. Returns an array of paths in the stack.
 function _pushd(options, dir) {
   if (_isStackIndex(options)) {
     dir = options;
@@ -101,12 +101,13 @@ function _pushd(options, dir) {
 }
 exports.pushd = _pushd;
 
+//@
 //@
 //@ ### popd([options,] ['-N' | '+N'])
 //@
 //@ Available options:
 //@
-//@ + `-n`: Suppresses the normal change of directory when removing directories from the stack, so that only the stack is manipulated.
+//@ + `-n`: Suppress the normal directory change when removing directories from the stack, so that only the stack is manipulated.
 //@ + `-q`: Supresses output to the console.
 //@
 //@ Arguments:
@@ -124,7 +125,7 @@ exports.pushd = _pushd;
 //@ echo(process.cwd()); // '/usr'
 //@ ```
 //@
-//@ When no arguments are given, popd removes the top directory from the stack and performs a cd to the new top directory. The elements are numbered from 0 starting at the first directory listed with dirs; i.e., popd is equivalent to popd +0. Returns an array of paths in the stack.
+//@ When no arguments are given, `popd` removes the top directory from the stack and performs a `cd` to the new top directory. The elements are numbered from 0, starting at the first directory listed with dirs (i.e., `popd` is equivalent to `popd +0`). Returns an array of paths in the stack.
 function _popd(options, index) {
   if (_isStackIndex(options)) {
     index = options;
@@ -154,6 +155,7 @@ function _popd(options, index) {
 }
 exports.popd = _popd;
 
+//@
 //@
 //@ ### dirs([options | '+N' | '-N'])
 //@
@@ -167,9 +169,9 @@ exports.popd = _popd;
 //@ + `+N`: Displays the Nth directory (counting from the left of the list printed by dirs when invoked without options), starting with zero.
 //@ + `-N`: Displays the Nth directory (counting from the right of the list printed by dirs when invoked without options), starting with zero.
 //@
-//@ Display the list of currently remembered directories. Returns an array of paths in the stack, or a single path if +N or -N was specified.
+//@ Display the list of currently remembered directories. Returns an array of paths in the stack, or a single path if `+N` or `-N` was specified.
 //@
-//@ See also: pushd, popd
+//@ See also: `pushd`, `popd`
 function _dirs(options, index) {
   if (_isStackIndex(options)) {
     index = options;

src/echo.js

@@ -8,6 +8,7 @@ common.register('echo', _echo, {
 
 //@
 //@ ### echo([options,] string [, string ...])
+//@
 //@ Available options:
 //@
 //@ + `-e`: interpret backslash escapes (default)
@@ -21,7 +22,7 @@ common.register('echo', _echo, {
 //@ echo('-n', 'no newline at end');
 //@ ```
 //@
-//@ Prints string to stdout, and returns string with additional utility methods
+//@ Prints `string` to stdout, and returns string with additional utility methods
 //@ like `.to()`.
 function _echo(opts) {
   // allow strings starting with '-', see issue #20

src/error.js

@@ -2,8 +2,9 @@ var common = require('./common');
 
 //@
 //@ ### error()
+//@
 //@ Tests if error occurred in the last command. Returns a truthy value if an
-//@ error returned and a falsy value otherwise.
+//@ error returned, or a falsy value otherwise.
 //@
 //@ **Note**: do not rely on the
 //@ return value to be an error message. If you need the last error message, use

src/exec.js

@@ -14,7 +14,7 @@ common.register('exec', _exec, {
   wrapOutput: false,
 });
 
-// We use this function to run exec synchronously while also providing realtime
+// We use this function to run `exec` synchronously while also providing realtime
 // output.
 function execSync(cmd, opts, pipe) {
   if (!common.config.execPath) {
@@ -138,15 +138,16 @@ function execAsync(cmd, opts, pipe, callback) {
 
 //@
 //@ ### exec(command [, options] [, callback])
+//@
 //@ Available options:
 //@
 //@ + `async`: Asynchronous execution. If a callback is provided, it will be set to
 //@   `true`, regardless of the passed value (default: `false`).
 //@ + `silent`: Do not echo program output to console (default: `false`).
-//@ + `encoding`: Character encoding to use. Affects the returned stdout and stderr values, and
+//@ + `encoding`: Character encoding to use. Affects the values returned to stdout and stderr, and
 //@   what is written to stdout and stderr when not in silent mode (default: `'utf8'`).
 //@ + and any option available to Node.js's
-//@   [child_process.exec()](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
+//@   [`child_process.exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
 //@
 //@ Examples:
 //@
@@ -166,17 +167,13 @@ function execAsync(cmd, opts, pipe, callback) {
 //@ ```
 //@
 //@ Executes the given `command` _synchronously_, unless otherwise specified.  When in synchronous
-//@ mode, this returns a ShellString (compatible with ShellJS v0.6.x, which returns an object
+//@ mode, this returns a `ShellString` (compatible with ShellJS v0.6.x, which returns an object
 //@ of the form `{ code:..., stdout:... , stderr:... }`). Otherwise, this returns the child process
-//@ object, and the `callback` gets the arguments `(code, stdout, stderr)`.
+//@ object, and the `callback` receives the arguments `(code, stdout, stderr)`.
 //@
 //@ Not seeing the behavior you want? `exec()` runs everything through `sh`
 //@ by default (or `cmd.exe` on Windows), which differs from `bash`. If you
 //@ need bash-specific behavior, try out the `{shell: 'path/to/bash'}` option.
-//@
-//@ **Note:** For long-lived processes, it's best to run `exec()` asynchronously as
-//@ the current synchronous implementation uses a lot of CPU. This should be getting
-//@ fixed soon.
 function _exec(command, options, callback) {
   options = options || {};
   if (!command) common.error('must specify command');

src/find.js

@@ -7,6 +7,7 @@ common.register('find', _find, {});
 //@
 //@ ### find(path [, path ...])
 //@ ### find(path_array)
+//@
 //@ Examples:
 //@
 //@ ```javascript
@@ -18,7 +19,7 @@ common.register('find', _find, {});
 //@ Returns array of all files (however deep) in the given paths.
 //@
 //@ The main difference from `ls('-R', path)` is that the resulting file names
-//@ include the base directories, e.g. `lib/resources/file1` instead of just `file1`.
+//@ include the base directories (e.g., `lib/resources/file1` instead of just `file1`).
 function _find(options, paths) {
   if (!paths) {
     common.error('no path specified');
@@ -35,8 +36,8 @@ function _find(options, paths) {
     list.push(file);
   }
 
-  // why not simply do ls('-R', paths)? because the output wouldn't give the base dirs
-  // to get the base dir in the output, we need instead ls('-R', 'dir/*') for every directory
+  // why not simply do `ls('-R', paths)`? because the output wouldn't give the base dirs
+  // to get the base dir in the output, we need instead `ls('-R', 'dir/*')` for every directory
 
   paths.forEach(function (file) {
     var stat;

src/grep.js

@@ -13,9 +13,10 @@ common.register('grep', _grep, {
 //@
 //@ ### grep([options,] regex_filter, file [, file ...])
 //@ ### grep([options,] regex_filter, file_array)
+//@
 //@ Available options:
 //@
-//@ + `-v`: Inverse the sense of the regex and print the lines not matching the criteria.
+//@ + `-v`: Invert `regex_filter` (only print non-matching lines).
 //@ + `-l`: Print only filenames of matching files
 //@
 //@ Examples:

src/head.js

@@ -33,6 +33,7 @@ function readSomeLines(file, numLines) {
 //@
 //@ ### head([{'-n': \<num\>},] file [, file ...])
 //@ ### head([{'-n': \<num\>},] file_array)
+//@
 //@ Available options:
 //@
 //@ + `-n <num>`: Show the first `<num>` lines of the files

src/ln.js

@@ -11,6 +11,7 @@ common.register('ln', _ln, {
 
 //@
 //@ ### ln([options,] source, dest)
+//@
 //@ Available options:
 //@
 //@ + `-s`: symlink
@@ -23,7 +24,7 @@ common.register('ln', _ln, {
 //@ ln('-sf', 'file', 'existing');
 //@ ```
 //@
-//@ Links source to dest. Use -f to force the link, should dest already exist.
+//@ Links `source` to `dest`. Use `-f` to force the link, should `dest` already exist.
 function _ln(options, source, dest) {
   if (!source || !dest) {
     common.error('Missing <source> and/or <dest>');

src/ls.js

@@ -19,6 +19,7 @@ common.register('ls', _ls, {
 //@
 //@ ### ls([options,] [path, ...])
 //@ ### ls([options,] path_array)
+//@
 //@ Available options:
 //@
 //@ + `-R`: recursive
@@ -27,7 +28,7 @@ common.register('ls', _ls, {
 //@ + `-d`: list directories themselves, not their contents
 //@ + `-l`: list objects representing each file, each with fields containing `ls
 //@         -l` output fields. See
-//@         [fs.Stats](https://nodejs.org/api/fs.html#fs_class_fs_stats)
+//@         [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)
 //@         for more info
 //@
 //@ Examples:
@@ -39,7 +40,8 @@ common.register('ls', _ls, {
 //@ ls('-l', 'file.txt'); // { name: 'file.txt', mode: 33188, nlink: 1, ...}
 //@ ```
 //@
-//@ Returns array of files in the given path, or in current directory if no path provided.
+//@ Returns array of files in the given `path`, or files in
+//@ the current directory if no `path` is  provided.
 function _ls(options, paths) {
   if (options.all_deprecated) {
     // We won't support the -a option as it's hard to image why it's useful

src/mkdir.js

@@ -8,7 +8,7 @@ common.register('mkdir', _mkdir, {
   },
 });
 
-// Recursively creates 'dir'
+// Recursively creates `dir`
 function mkdirSyncRecursive(dir) {
   var baseDir = path.dirname(dir);
 
@@ -35,9 +35,10 @@ function mkdirSyncRecursive(dir) {
 //@
 //@ ### mkdir([options,] dir [, dir ...])
 //@ ### mkdir([options,] dir_array)
+//@
 //@ Available options:
 //@
-//@ + `-p`: full path (will create intermediate dirs if necessary)
+//@ + `-p`: full path (and create intermediate directories, if necessary)
 //@
 //@ Examples:
 //@

src/mv.js

@@ -22,6 +22,7 @@ function checkRecentCreated(sources, index) {
 //@
 //@ ### mv([options ,] source [, source ...], dest')
 //@ ### mv([options ,] source_array, dest')
+//@
 //@ Available options:
 //@
 //@ + `-f`: force (default behavior)
@@ -35,7 +36,7 @@ function checkRecentCreated(sources, index) {
 //@ mv(['file1', 'file2'], 'dir/'); // same as above
 //@ ```
 //@
-//@ Moves files.
+//@ Moves `source` file(s) to `dest`.
 function _mv(options, sources, dest) {
   // Get sources, dest
   if (arguments.length < 3) {

src/pwd.js

@@ -7,6 +7,7 @@ common.register('pwd', _pwd, {
 
 //@
 //@ ### pwd()
+//@
 //@ Returns the current directory.
 function _pwd() {
   var pwd = path.resolve(process.cwd());

src/rm.js

@@ -149,6 +149,7 @@ function handleFIFO(file) {
 //@
 //@ ### rm([options,] file [, file ...])
 //@ ### rm([options,] file_array)
+//@
 //@ Available options:
 //@
 //@ + `-f`: force