docs: better describe semantics of exec

packages/exec/README.md

@@ -22,26 +22,24 @@ const exec = require('@actions/exec');
 await exec.exec('node', ['index.js', 'foo=bar']);
 ```
 
+#### Capture stdout
+To capture stdout (or stderr), use the function `getExecOutput`.
+```js
+const exec = require('@actions/exec');
+
+const { stdout } = await exec.getExecOutput('node', ['index.js', 'foo=bar']);
+```
 #### Output/options
 
-Capture output or specify [other options](https://github.com/actions/toolkit/blob/d9347d4ab99fd507c0b9104b2cf79fb44fcc827d/packages/exec/src/interfaces.ts#L5):
+Specify [other options](https://github.com/actions/toolkit/blob/main/packages/exec/src/interfaces.ts#L5):
 
 ```js
 const exec = require('@actions/exec');
 
-let myOutput = '';
-let myError = '';
-
-const options = {};
-options.listeners = {
-  stdout: (data: Buffer) => {
-    myOutput += data.toString();
-  },
-  stderr: (data: Buffer) => {
-    myError += data.toString();
-  }
+const options = {
+  silent: true,
+  ignoreReturnCode: true,
 };
-options.cwd = './lib';
 
 await exec.exec('node', ['index.js', 'foo=bar'], options);
 ```

packages/exec/src/exec.ts

@@ -5,9 +5,13 @@ import * as tr from './toolrunner'
 export {ExecOptions, ExecOutput, ExecListeners}
 
 /**
- * Exec a command.
+ * Execute a command.
  * Output will be streamed to the live console.
- * Returns promise with return code
+ *
+ * This functions returns a promise with the exit code.
+ * Unless `ignoreReturnCode` is passed via `options`, this function is going to return a rejected promise if the process exists with a non-zero code.
+ *
+ * If you want an easy way to capture the output of the command, use the function `getExecOutput`.
  *
  * @param     commandLine        command to execute (can include additional args). Must be correctly escaped.
  * @param     args               optional arguments for tool. Escaping is handled by the lib.