Document steps in nyc execution

[dtgriscom]

I'm using nyc to capture code coverage in my TypeScript project, and it's working well (excellent tool). However, now that I want to do more sophisticated things (e.g. merge multiple coverage captures into a single report) I'm finding that there's a total lack of documentation on just what steps nyc takes when it runs, and how to control them.

After a lot of sniffing around the various fragments of doc and --help output, I believe the default process is something like the following:

1. Delete contents of .nyc_output
2. Run node, loading target .js file
   a. Whenever node loads a .js file, instrument it (default is to cache results)
   b. Run target code, accumulating coverage data in __coverage__ object
   c. Continue until target project exits
3. Write captured coverage data to a single .nyc_output/ReallyLongRandomHexFileName.json file
4. Read .nyc_output/*.json files back in (?), merging all data into single representation of coverage
5. Generate each requested report

Did I get this right? If so, how can I control this sequence? For instance, I'd like to:

• Disable deletion of previous .nyc_output/ReallyLongRandomHexFileName.json files (--clean=false option, I believe, although I'm not sure of the syntax)
• Disable report generation (--silent option, I believe)
• Just generate reports from all merged .nyc_output/ReallyLongRandomHexFileName.json files (the report command, I believe)

If I got all this right, then please consider this a request for documentation; basic issues like this probably get in the way of a lot of potential nyc users. (In theory I could write the doc myself and submit a pull request, but I don't have a good feel for where in the doc tree it should be placed.)

[JaKXz]

@dtgriscom I appreciate this issue, sorry it's taken so long to get back to you.

I would love to see a PR here, under the docs/advanced features section: https://github.com/istanbuljs/istanbuljs.github.io/tree/development/content/docs/advanced