google / google/closure-compiler
Some compilation flags are unclear
- Dominant language
- JavaScript
- Stars
- 7.7k
- Forks
- 1.2k
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 6
Description
Some compilation flags are unclear, hard to understand or find out what they do or insufficiently documented. Specifically, I am talking about [the wiki section on compiler flags](https://github.com/google/closure-compiler/wiki/Flags-and-Options).
Let's have a look at some of those flags:
1. `compilation_level` - what does `--compilation_level=BUNDLE` do? Compilation level is described [here in the Google doc](https://developers.google.com/closure/compiler/docs/compilation_levels) but there is no mention of `BUNDLE`. Plus it would be great if each option was described in a bit more detail, or at least via a link.
2. `env` - what is `--env=CUSTOM` and how to use it?
3. `externs` - shouldn't this be deprecated [as explained here in the Google doc?](https://developers.google.com/closure/compiler/docs/externs-and-exports#externs_cli)
4. `warning_level` - the default warning level value is `DEFAULT` ... what does that mean?
5. `process_common_js_modules` - this should probably be `true` by default ([as mentioned here](https://github.com/google/closure-compiler/issues/3714#issuecomment-721084844)), or in case it is experimental, it should be marked as experimental
6. `module_resolution` - what is `--module_resolution=BROWSER_WITH_TRANSFORMED_PREFIXES`, what is `--module_resolution=WEBPACK`? These options should be described in a bit more detail, or via a link. What is the difference between `WEBPACK` and `NODE`? It should also be noted that in order to import from `node_modules`, `--module_resolution=NODE` must be used, nothing else seems to work for that.
7. `force_inject_library` - what is `base` and `es6_runtime`? I thought `base` was Google Closure base.js but it does not seem so.
8. `source_map_input`, `source_map_location_mapping` - what is the difference between them? Maybe give an example.
9. `third_party` - it is described as "Check source validity but do not enforce Closure style rules and conventions" ... what are the Closure style rules? Where can I find documentation on that?
10. `js` - it should be mentioned that these are Javascript input files to be bundled. It should also mention that in order to use libraries from `node_modules`, the JS files and `package.json` from `node_modules` must be listed here as well. On top of that, **externs** files, which are not really source files but rather API/structure definitions, should be listed here as well.
Compiler Version: v20230103
Contributor guide
Assessment
This issue has not been assessed yet.