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

mhegazy · 2017-02-09T18:29:21Z

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"
  ]
}

…e all options generated

mhegazy · 2017-03-21T22:35:06Z

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.

DanielRosenwasser · 2017-03-21T22:18:20Z

src/compiler/diagnosticMessages.json

        "code": 6149
    },
-    "Enable all strict type checks.": {
+    "Show extended diagnostic information.": {


"verbose" or "detailed"

DanielRosenwasser · 2017-03-21T22:22:07Z

src/compiler/diagnosticMessages.json

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


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

DanielRosenwasser · 2017-03-21T22:26:03Z

src/compiler/diagnosticMessages.json

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


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

DanielRosenwasser · 2017-03-21T22:26:26Z

src/compiler/diagnosticMessages.json

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


Single quotes around __extends

DanielRosenwasser · 2017-03-21T22:34:17Z

src/compiler/diagnosticMessages.json

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


or module import targets -> or imported modules

DanielRosenwasser · 2017-03-21T22:48:07Z

src/compiler/diagnosticMessages.json

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


Command-line Options

DanielRosenwasser · 2017-03-21T22:49:06Z

src/compiler/diagnosticMessages.json

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


Strict Type-Checking Options

DanielRosenwasser · 2017-03-21T22:49:32Z

src/compiler/diagnosticMessages.json

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


DanielRosenwasser · 2017-03-21T22:50:05Z

src/compiler/diagnosticMessages.json

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


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

DanielRosenwasser · 2017-03-21T22:51:39Z

src/compiler/diagnosticMessages.json

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


language service plugins

DanielRosenwasser · 2017-03-22T19:40:32Z

src/compiler/tsc.ts

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


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

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

mhegazy · 2017-03-22T20:12:30Z

@DanielRosenwasser, any other comments?

mihailik · 2017-03-23T14:39:55Z

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

mhegazy · 2017-03-23T17:00:32Z

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 · 2017-05-12T19:21:59Z

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 · 2017-05-12T19:36:41Z

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 · 2017-05-12T19:54:23Z

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.

mhegazy added 10 commits February 7, 2017 21:54

Make sure all options have descriptions

57f2fbd

Manually order options

3459719

Add simplified help view and full help view

486757f

Add deprecation notice for some options

6837125

use category in serializeCompilerOptions

f53eeae

Make generateTSConfig return a string

0bc2840

Write comments for compiler options in tsc --init output

9fc4f6e

Remove properties from tsconfig.json that defaults to false

1c0ca7c

Make categories localizable

c97673c

Mark some more options as advanced

4de44ee

msftclas added the cla-not-required label Feb 9, 2017

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

mhegazy added 3 commits February 13, 2017 22:13

Accept baseline recursivelly

abae1bd

Accept baselines

6613530

Fix lint failures

2752bfb

mhegazy added the Salsa label Mar 1, 2017

mhegazy added 7 commits March 15, 2017 15:38

Merge branch 'master' into optionsDescription

7d56837

Remove compileOnSave from compiler option

f2654c6

Print comments in a diffrent column

efa3093

rename catogories, and reorder options

5bbd8f8

Remove sourceMap:false from default compiler optios now that we hav…

5016141

…e all options generated

Fix bad merge

b6ccad4

Accept baselines

0112a38

mhegazy closed this Mar 16, 2017

mhegazy reopened this Mar 16, 2017

msftclas added the cla-not-required label Mar 16, 2017

Normalize line endings when validating baselines

d78e5a1

DanielRosenwasser requested changes Mar 21, 2017

View reviewed changes

Merge branch 'master' into optionsDescription

b2f49cc

Code review comments

d906e91

DanielRosenwasser requested changes Mar 22, 2017

View reviewed changes

mhegazy added 3 commits March 22, 2017 12:41

Remove BOM

88b88e1

Show help if --all is specifided without --help

ae1983b

Format else clauses

11d1409

DanielRosenwasser approved these changes Mar 22, 2017

View reviewed changes

mhegazy merged commit aad80ad into master Mar 22, 2017

DanielRosenwasser deleted the optionsDescription branch March 22, 2017 22:48

microsoft locked and limited conversation to collaborators Jun 19, 2018

Simplified help, and enhanced --init output #13982

Simplified help, and enhanced --init output #13982

Uh oh!

Conversation

mhegazy commented Feb 9, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mhegazy commented Mar 21, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielRosenwasser Mar 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mhegazy commented Mar 22, 2017

Uh oh!

mihailik commented Mar 23, 2017

Uh oh!

mhegazy commented Mar 23, 2017

Uh oh!

borekb commented May 12, 2017

Uh oh!

mhegazy commented May 12, 2017

Uh oh!

borekb commented May 12, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

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

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

mhegazy commented Feb 9, 2017 •

edited

Loading

DanielRosenwasser Mar 22, 2017 •

edited

Loading