CLIEngine docs do not explicitly indicate that fix option does not write to disk

[NickHeiner]

What version of ESLint are you using?
2.12.0

What parser (default, Babel-ESLint, etc.) are you using?
default

Please show your full configuration:
demo.js

const CLIEngine = require('eslint').CLIEngine;
const eslintCli = new CLIEngine({
    rules: {
        'comma-dangle': 'error'
    },
    fix: true
});

const report = eslintCli.executeOnFiles(['sample.js']);

console.log(report);

console.log(eslintCli.getFormatter()(report.results));

What did you do? Please include the actual source code causing the issue.
The file I linted:

sample.js

var obj = {
    comma: 'dangle',
};

Running the linter:

λ node demo.js 
{ results: 
   [ { filePath: '/Users/nick.heiner/opower/x-web-sdk/cli-x-web/sample.js',
       messages: [],
       errorCount: 0,
       warningCount: 0,
       output: 'var obj = {\n    comma: \'dangle\'\n};\n' } ],
  errorCount: 0,
  warningCount: 0 }

What did you expect to happen?
I was hoping that the fix would be applied to the file on disk.

What actually happened? Please include the actual, raw output from ESLint.
The fix was not applied to the file on disk. Looking through the code, it appears that this is the intended behavior. If I just write result.output to result.filePath, then I'll be set. However, this was confusing for me because the NodeJS API docs say:

fix - True indicates that fixes should be applied to the text when possible.

If I'm understanding correctly, it would be more accurate to say:

fix - True indicates that fixes should be included with the output report, and that errors and warnings should not be listed if they can be fixed. However, the files on disk will not be changed. It is up to you to do this manually. Within a result object, result.output is the fixed code. You can write this code to disk to persist the fix.

[platinumazure]

CLIEngine does not automatically output fixes to disk in case it is being used in a toolchain which might be better positioned to do so (e.g., Grunt/Gulp). Instead, executeOnFiles() includes output properties showing the fixed text (as you have observed).

In order to write the outputs to disk, you can call CLIEngine.outputFixes() after running the executeOnFiles().

[platinumazure]

That said, it certainly couldn't hurt to call out that, in executeOnFiles(), we don't apply fixes to disk, and that to do so requires calling CLIEngine.outputFixes(). I'll let the @eslint/eslint-team decide if this is a worthwhile documentation improvement.

[NickHeiner]

Ah, of course! I'd missed the docs for CLIEngine.outputFixes.

I'd be happy to submit a PR rewording the docs myself if you'd be amenable.

[platinumazure]

@NickHeiner No worries, I agree it could be clearer.

We usually like to get consensus among ESLint team members before accepting issues, but I'm fairly sure this will be accepted easily. So please feel free to submit a PR (with the caveat that there is a very tiny chance of this issue being rejected and then you would have waste your time, but again that chance should be very small). Thanks!