New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplified help, and enhanced `--init` output #13982

Merged
merged 26 commits into from Mar 22, 2017

Conversation

Projects
None yet
5 participants
@mhegazy
Copy link
Contributor

mhegazy commented Feb 9, 2017

This change includes a few changes:

  • Add description to all our command-line options
  • Show select set of options in the main help list
  • Add --help --all to show all help options
  • tsc --init produce a file with comments for "popular" options and will arrange them in categories, e.g. Strict Checks, Module Resolution, SourceMap Options

The result of tsc --init looks something like:

{
  "compilerOptions": {
    /* Basic Options */
    "target": "es5",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'. */
    "module": "commonjs",                     /* Specify module code generation: 'commonjs', 'amd', 'system', 'umd' or 'es2015'. */
    // "lib": [],                             /* Specify library files to be included in the compilation:  */
    // "allowJs": true,                       /* Allow javascript files to be compiled. */
    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
    // "declaration": true,                   /* Generates corresponding '.d.ts' file. */
    "sourceMap": false,                       /* Generates corresponding '.map' file. */
    // "outFile": "./",                       /* Concatenate and emit output to single file. */
    // "outDir": "./",                        /* Redirect output structure to the directory. */
    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
    // "removeComments": true,                /* Do not emit comments to output. */
    // "noEmit": true,                        /* Do not emit outputs. */
    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
    // "downlevelIteration": true,            /* Use full down-level iteration for iterables and arrays for 'for-of', spread, and destructuring in ES5/3. */
    // "isolatedModules": true,               /* Unconditionally emit imports for unresolved files. */

    /* Strict Type Checks */
    "strict": true                            /* Enable all strict type checks. */
    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
    // "strictNullChecks": true,              /* Enable strict null checks. */
    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */

    /* Additional Checks */
    // "noUnusedLocals": true,                /* Report errors on unused locals. */
    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */

    /* Module Resolution Options */
    // "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
    // "paths": {},                           /* List of path mapping entries for module names to locations relative to the 'baseUrl'. */
    // "rootDirs": [],                        /* List of root folders whose combined content represent the structure of the project at runtime. */
    // "typeRoots": [],                       /* List of folders to include type definitions from. */
    // "types": [],                           /* Type declaration files to be included in compilation. */
    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */

    /* SourceMap Options */
    // "sourceRoot": "./",                    /* Specify the location where debugger should locate TypeScript files instead of source locations. */
    // "mapRoot": "./",                       /* Specify the location where debugger should locate map files instead of generated locations. */
    // "inlineSourceMap": false,              /* Emit a single file with source maps instead of having a separate file. */
    // "inlineSources": false                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */

    /* Experimental Options */
    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
  },
  "files": [
    "c:\\test\\a.ts",
    "c:\\test\\b.ts"
  ]
}

@mhegazy mhegazy changed the title Options description Simplified help, and enhanced `--init` output Feb 9, 2017

@mhegazy mhegazy added the Salsa label Mar 1, 2017

@mhegazy mhegazy closed this Mar 16, 2017

@mhegazy mhegazy reopened this Mar 16, 2017

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented Mar 21, 2017

here is the output of the help for review purposes:

c:\ts>node built\local\tsc.js --help
Version 2.3.0
Syntax:   tsc [options] [file ...]

Examples: tsc hello.ts
          tsc --outFile file.js file.ts
          tsc @args.txt

Options:
 -h, --help                                         Print this message.
 --all                                              Show all compiler options.
 -v, --version                                      Print the compiler's version.
 --init                                             Initializes a TypeScript project and creates a tsconfig.json file.
 -p FILE OR DIRECTORY, --project FILE OR DIRECTORY  Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
 --pretty                                           Stylize errors and messages using color and context (experimental).
 -w, --watch                                        Watch input files.
 -t VERSION, --target VERSION                       Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'.
 -m KIND, --module KIND                             Specify module code generation: 'commonjs', 'amd', 'system', 'umd' or 'es2015'.
 --lib                                              Specify library files to be included in the compilation:
                                                      'es5' 'es6' 'es2015' 'es7' 'es2016' 'es2017' 'esnext' 'dom' 'dom.iterable' 'webworker' 'scripthost' 'es2015.core' 'es2015.collection' 'es2015.generator' 'es2015.iterable' 'es2015.promise' 'es2015.proxy' 'es2015.reflect' 'es2015.symbol' 'es2015.symbol.wellknown' 'es2016.array.include' 'es2017.object' 'es2017.sharedmemory' 'es2017.string' 'esnext.asynciterable'
 --allowJs                                          Allow javascript files to be compiled.
 --jsx KIND                                         Specify JSX code generation: 'preserve', 'react-native', or 'react'.
 -d, --declaration                                  Generates corresponding '.d.ts' file.
 --sourceMap                                        Generates corresponding '.map' file.
 --outFile FILE                                     Concatenate and emit output to single file.
 --outDir DIRECTORY                                 Redirect output structure to the directory.
 --removeComments                                   Do not emit comments to output.
 --noEmit                                           Do not emit outputs.
 --strict                                           Enable all strict type checks.
 --noImplicitAny                                    Raise error on expressions and declarations with an implied 'any' type.
 --strictNullChecks                                 Enable strict null checks.
 --noImplicitThis                                   Raise error on 'this' expressions with an implied 'any' type.
 --alwaysStrict                                     Parse in strict mode and emit "use strict" for each source file.
 --noUnusedLocals                                   Report errors on unused locals.
 --noUnusedParameters                               Report errors on unused parameters.
 --noImplicitReturns                                Report error when not all code paths in function return a value.
 --noFallthroughCasesInSwitch                       Report errors for fallthrough cases in switch statement.
 --types                                            Type declaration files to be included in compilation.
 @<file>                                            Insert command line options and files from a file.

c:\ts>node built\local\tsc.js --help --all
Version 2.3.0
Syntax:   tsc [options] [file ...]

Examples: tsc hello.ts
          tsc --outFile file.js file.ts
          tsc @args.txt

Options:
 --all                                              Show all compiler options.
 --allowJs                                          Allow javascript files to be compiled.
 --allowSyntheticDefaultImports                     Allow default imports from modules with no default export. This does not affect code emit, just typechecking.
 --allowUnreachableCode                             Do not report errors on unreachable code.
 --allowUnusedLabels                                Do not report errors on unused labels.
 --alwaysStrict                                     Parse in strict mode and emit "use strict" for each source file.
 --baseUrl                                          Base directory to resolve non-absolute module names.
 --charset                                          The character set of the input files.
 -d, --declaration                                  Generates corresponding '.d.ts' file.
 --declarationDir DIRECTORY                         Output directory for generated declaration files.
 --diagnostics                                      Show diagnostic information.
 --disableSizeLimit                                 Disable size limitation on JavaScript project.
 --downlevelIteration                               Use full down-level iteration for iterables and arrays for 'for-of', spread, and destructuring in ES5/3.
 --emitBOM                                          Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.
 --emitDecoratorMetadata                            Enables experimental support for emitting type metadata for decorators.
 --experimentalDecorators                           Enables experimental support for ES7 decorators.
 --extendedDiagnostics                              Show extended diagnostic information.
 --forceConsistentCasingInFileNames                 Disallow inconsistently-cased references to the same file.
 -h, --help                                         Print this message.
 --importHelpers                                    Import emit helpers from 'tslib'.
 --init                                             Initializes a TypeScript project and creates a tsconfig.json file.
 --inlineSourceMap                                  Emit a single file with source maps instead of having a separate file.
 --inlineSources                                    Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set.
 --isolatedModules                                  Unconditionally emit imports for unresolved files.
 --jsx KIND                                         Specify JSX code generation: 'preserve', 'react-native', or 'react'.
 --jsxFactory                                       Specify the JSX factory function to use when targeting 'react' JSX emit, e.g. 'React.createElement' or 'h'.
 --lib                                              Specify library files to be included in the compilation:
                                                      'es5' 'es6' 'es2015' 'es7' 'es2016' 'es2017' 'esnext' 'dom' 'dom.iterable' 'webworker' 'scripthost' 'es2015.core' 'es2015.collection' 'es2015.generator' 'es2015.iterable' 'es2015.promise' 'es2015.proxy' 'es2015.reflect' 'es2015.symbol' 'es2015.symbol.wellknown' 'es2016.array.include' 'es2017.object' 'es2017.sharedmemory' 'es2017.string' 'esnext.asynciterable'
 --listEmittedFiles                                 Print names of generated files part of the compilation.
 --listFiles                                        Print names of files part of the compilation.
 --locale                                           The locale to use to show error messages, e.g. 'en-us'.
 --mapRoot LOCATION                                 Specify the location where debugger should locate map files instead of generated locations.
 --maxNodeModuleJsDepth                             The maximum dependency depth to search under node_modules and load JavaScript files.
 -m KIND, --module KIND                             Specify module code generation: 'commonjs', 'amd', 'system', 'umd' or 'es2015'.
 --moduleResolution STRATEGY                        Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6).
 --newLine NEWLINE                                  Specify the end of line sequence to be used when emitting files: 'CRLF' (dos) or 'LF' (unix).
 --noEmit                                           Do not emit outputs.
 --noEmitHelpers                                    Do not generate custom helper functions like __extends in compiled output.
 --noEmitOnError                                    Do not emit outputs if any errors were reported.
 --noErrorTruncation                                Do not truncation error messages.
 --noFallthroughCasesInSwitch                       Report errors for fallthrough cases in switch statement.
 --noImplicitAny                                    Raise error on expressions and declarations with an implied 'any' type.
 --noImplicitReturns                                Report error when not all code paths in function return a value.
 --noImplicitThis                                   Raise error on 'this' expressions with an implied 'any' type.
 --noImplicitUseStrict                              Do not emit 'use strict' directives in module output.
 --noLib                                            Do not include the default library file (lib.d.ts).
 --noResolve                                        Do not add triple-slash references or module import targets to the list of compiled files.
 --noUnusedLocals                                   Report errors on unused locals.
 --noUnusedParameters                               Report errors on unused parameters.
 --out FILE                                         [Deprecated] Use '--outFile' instead. Concatenate and emit output to single file
 --outDir DIRECTORY                                 Redirect output structure to the directory.
 --outFile FILE                                     Concatenate and emit output to single file.
 --paths                                            List of path mapping entries for module names to locations relative to the 'baseUrl'.
 --plugins                                          List of Language Service plugins.
 --preserveConstEnums                               Do not erase const enum declarations in generated code.
 --pretty                                           Stylize errors and messages using color and context (experimental).
 -p FILE OR DIRECTORY, --project FILE OR DIRECTORY  Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
 --reactNamespace                                   [Deprecated] Use '--jsxFactory' instead. Specify the object invoked for createElement when targeting 'react' JSX emit
 --removeComments                                   Do not emit comments to output.
 --rootDir LOCATION                                 Specify the root directory of input files. Use to control the output directory structure with --outDir.
 --rootDirs                                         List of root folders whose combined content represent the structure of the project at runtime.
 --skipDefaultLibCheck                              [Deprecated] Use '--skipLibCheck' instead. Skip type checking of default library declaration files.
 --skipLibCheck                                     Skip type checking of declaration files.
 --sourceMap                                        Generates corresponding '.map' file.
 --sourceRoot LOCATION                              Specify the location where debugger should locate TypeScript files instead of source locations.
 --strict                                           Enable all strict type checks.
 --strictNullChecks                                 Enable strict null checks.
 --stripInternal                                    Do not emit declarations for code that has an '@internal' annotation.
 --suppressExcessPropertyErrors                     Suppress excess property checks for object literals.
 --suppressImplicitAnyIndexErrors                   Suppress noImplicitAny errors for indexing objects lacking index signatures.
 -t VERSION, --target VERSION                       Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'.
 --traceResolution                                  Enable tracing of the name resolution process.
 --typeRoots                                        List of folders to include type definitions from.
 --types                                            Type declaration files to be included in compilation.
 -v, --version                                      Print the compiler's version.
 -w, --watch                                        Watch input files.
 @<file>                                            Insert command line options and files from a file.
"category": "Message",
"code": 6149
},
"Enable all strict type checks.": {
"Show extended diagnostic information.": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

"verbose" or "detailed"

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6152
},
"Unconditionally emit imports for unresolved files.": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

Seems like that's not the only thing this does :(

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6155
},
"The locale to use to show error messages, e.g. 'en-us'.": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

The locale use when displaying messages to the user (e.g. 'en-us').

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6156
},
"Do not generate custom helper functions like __extends in compiled output.": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

Single quotes around __extends

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6158
},
"Do not add triple-slash references or module import targets to the list of compiled files.": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

or module import targets -> or imported modules

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6170
},
"CommandLine Options": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

Command-line Options

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6172
},
"Strict Type Checks": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

Strict Type-Checking Options

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6174
},
"SourceMap Options": {

This comment has been minimized.

@DanielRosenwasser
"category": "Message",
"code": 6178
},
"Use full down-level iteration for iterables and arrays for 'for-of', spread, and destructuring in ES5/3.": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

Provide full support for iterables in for-of, spread, and destructuring when targeting ES5 & ES3.

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

"category": "Message",
"code": 6180
},
"List of Language Service plugins.": {

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 21, 2017

Member

language service plugins

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

@@ -227,7 +227,7 @@ namespace ts {

if (commandLine.options.help) {
printVersion();
printHelp();
printHelp(commandLine.options.all);

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 22, 2017

Member

Feels strange that you won't get help output if you only provide --all. Either check for it as well, give an error if help is not provided, or create a --help-all

This comment has been minimized.

@DanielRosenwasser

DanielRosenwasser Mar 22, 2017

Member

Also, do we believe we won't use --all for something else?

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

sure

This comment has been minimized.

@mhegazy

mhegazy Mar 22, 2017

Contributor

done.

mhegazy added some commits Mar 22, 2017

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented Mar 22, 2017

@DanielRosenwasser, any other comments?

@mhegazy mhegazy merged commit aad80ad into master Mar 22, 2017

4 checks passed

TypeScript Test Run typescript_node.4 Build finished.
Details
TypeScript Test Run typescript_node.6 Build finished.
Details
TypeScript Test Run typescript_node.stable Build finished.
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@DanielRosenwasser DanielRosenwasser deleted the optionsDescription branch Mar 22, 2017

@mihailik

This comment has been minimized.

Copy link
Contributor

mihailik commented Mar 23, 2017

sourceMap and sourceRoot and handful of other source map-related options grouped in different places in tsc --init.

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented Mar 23, 2017

SourceMap should be the only one that is in "Basic", the other source map flags should be under "Source Map Options". it seemed that most users would be interested in setting up source maps, but very few would be interested in the "advanced" source map options.

@borekb

This comment has been minimized.

Copy link

borekb commented May 12, 2017

You guys realize that tsconfig.json is no longer a JSON after this PR, right? (I'm a big proponent of comments and trailing commas in JSONs, however, the standard it what it is and if there's any tool out there that parses tsconfig.json and expects it to be a JSON, it will fail.)

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented May 12, 2017

You guys realize that tsconfig.json is no longer a JSON after this PR, right? (I'm a big proponent of comments and trailing commas in JSONs, however, the standard it what it is and if there's any tool out there that parses tsconfig.json and expects it to be a JSON, it will fail.)

yes. this was the original apprehension to adding comments to the file.

We have since added support for stripping comments in the compiler and the compiler API, we have also seen other tools do that like VSCode for instance.

Overall the value and expressiveness of the comments is big, and users are always welcome to define the files themselves, tsc --init is not a requirement for any scenario.

@borekb

This comment has been minimized.

Copy link

borekb commented May 12, 2017

TypeScript chose a format that explicitly doesn't support comments only to fight it later :) But I understand, in our own projects, we have a similar dilemma: JSON is pretty close to being a great config format, except for comments.

@Microsoft Microsoft locked and limited conversation to collaborators Jun 19, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.