diff --git a/.gitignore b/.gitignore index 11cfefed5f2..a05a65c95c1 100644 --- a/.gitignore +++ b/.gitignore @@ -36,4 +36,5 @@ tests/*.d.ts *.config scripts/debug.bat scripts/run.bat +scripts/word2md.js coverage/ diff --git a/Jakefile b/Jakefile index 04049837f6e..db8d670b0bf 100644 --- a/Jakefile +++ b/Jakefile @@ -2,6 +2,7 @@ var fs = require("fs"); var path = require("path"); +var child_process = require("child_process"); // Variables var compilerDirectory = "src/compiler/"; @@ -9,6 +10,7 @@ var servicesDirectory = "src/services/"; var harnessDirectory = "src/harness/"; var libraryDirectory = "src/lib/"; var scriptsDirectory = "scripts/"; +var docDirectory = "doc/"; var builtDirectory = "built/"; var builtLocalDirectory = "built/local/"; @@ -260,6 +262,38 @@ task("clean", function() { jake.rmRf(builtDirectory); }); +// Generate Markdown spec +var word2mdJs = path.join(scriptsDirectory, "word2md.js"); +var word2mdTs = path.join(scriptsDirectory, "word2md.ts"); +var specWord = path.join(docDirectory, "TypeScript Language Specification.docx"); +var specMd = path.join(docDirectory, "spec.md"); +var headerMd = path.join(docDirectory, "header.md"); + +file(word2mdTs); + +// word2md script +compileFile(word2mdJs, + [word2mdTs], + [word2mdTs], + [], + false); + +// The generated spec.md; built for the 'generate-spec' task +file(specMd, [word2mdJs, specWord], function () { + jake.cpR(headerMd, specMd, {silent: true}); + var specWordFullPath = path.resolve(specWord); + var cmd = "cscript //nologo " + word2mdJs + ' "' + specWordFullPath + '" >>' + specMd; + console.log(cmd); + child_process.exec(cmd, function () { + complete(); + }); +}, {async: true}) + + +desc("Generates a Markdown version of the Language Specification"); +task("generate-spec", [specMd]) + + // Makes a new LKG. This target does not build anything, but errors if not all the outputs are present in the built/local directory desc("Makes a new LKG out of the built js files"); task("LKG", libraryTargets, function() { diff --git a/doc/TypeScript Language Specification.docx b/doc/TypeScript Language Specification.docx index 403daa64ad1..d3a189853c5 100644 Binary files a/doc/TypeScript Language Specification.docx and b/doc/TypeScript Language Specification.docx differ diff --git a/doc/spec.md b/doc/spec.md index 50f4c07fb00..aff7e06f469 100644 --- a/doc/spec.md +++ b/doc/spec.md @@ -102,9 +102,9 @@ TypeScript is a trademark of Microsoft Corporation. * [4.14.5 The void Operator](#4.14.5) * [4.14.6 The typeof Operator](#4.14.6) * [4.15 Binary Operators](#4.15) - * [4.15.1 The *, /, %, –, <<, >>, >>>, &, ^, and | operators](#4.15.1) + * [4.15.1 The *, /, %, –, <<, >>, >>>, &, ^, and | operators](#4.15.1) * [4.15.2 The + operator](#4.15.2) - * [4.15.3 The <, >, <=, >=, ==, !=, ===, and !== operators](#4.15.3) + * [4.15.3 The <, >, <=, >=, ==, !=, ===, and !== operators](#4.15.3) * [4.15.4 The instanceof operator](#4.15.4) * [4.15.5 The in operator](#4.15.5) * [4.15.6 The && operator](#4.15.6) @@ -1088,7 +1088,7 @@ Since a type parameter represents a multitude of different type arguments, type ### 3.4.1 Type Parameter Lists -Class, interface, and function declarations may optionally include lists of type parameters enclosed in < and > brackets. Type parameters are also permitted in call signatures of object, function, and constructor type literals. +Class, interface, and function declarations may optionally include lists of type parameters enclosed in < and > brackets. Type parameters are also permitted in call signatures of object, function, and constructor type literals.   *TypeParameters:*    `<` *TypeParameterList* `>` @@ -1149,7 +1149,7 @@ Given the declaration interface G { } ``` -a type reference of the form ‘G’ places no requirements on ‘A’ but requires ‘B’ to be assignable to ‘Function’. +a type reference of the form ‘G<A, B>’ places no requirements on ‘A’ but requires ‘B’ to be assignable to ‘Function’. The process of substituting type arguments for type parameters in a generic type or generic signature is known as ***instantiating*** the generic type or signature. Instantiation of a generic type or signature can fail if the supplied type arguments do not satisfy the constraints of their corresponding type parameters. @@ -1354,13 +1354,13 @@ Object type literals are the primary form of type literals and are described in As the table above illustrates, an array type literal is shorthand for a reference to the generic interface type ‘Array’ in the global module, a function type literal is shorthand for an object type containing a single call signature, and a constructor type literal is shorthand for an object type containing a single construct signature. Note that function and constructor types with multiple call or construct signatures cannot be written as function or constructor type literals but must instead be written as object type literals. -In order to avoid grammar ambiguities, array type literals permit only a restricted set of notations for the element type. Specifically, an A*rrayType* cannot start with a *FunctionType* or *ConstructorType*. To use one of those forms for the element type, an array type must be written using the ‘Array’ notation. For example, the type +In order to avoid grammar ambiguities, array type literals permit only a restricted set of notations for the element type. Specifically, an *ArrayType* cannot start with a *FunctionType* or *ConstructorType*. To use one of those forms for the element type, an array type must be written using the ‘Array<T>’ notation. For example, the type ```TypeScript () => string[] ``` -denotes a function returning a string array, not an array of functions returning string. The latter can be expressed using ‘Array’ notation +denotes a function returning a string array, not an array of functions returning string. The latter can be expressed using ‘Array<T>’ notation ```TypeScript Array<() => string> @@ -1833,7 +1833,7 @@ interface List { } ``` -‘List’ has a member ‘owner’ of type ‘List>’, which has a member ‘owner’ of type ‘List>>’, which has a member ‘owner’ of type ‘List>>>’ and so on, ad infinitum. Since type relationships are determined structurally, possibly exploring the constituent types to their full depth, in order to determine type relationships involving infinitely expanding generic types it may be necessary for the compiler to terminate the recursion at some point with the assumption that no further exploration will change the outcome. +‘List<T>’ has a member ‘owner’ of type ‘List<List<T>>’, which has a member ‘owner’ of type ‘List<List<List<T>>>’, which has a member ‘owner’ of type ‘List<List<List<List<T>>>>’ and so on, ad infinitum. Since type relationships are determined structurally, possibly exploring the constituent types to their full depth, in order to determine type relationships involving infinitely expanding generic types it may be necessary for the compiler to terminate the recursion at some point with the assumption that no further exploration will change the outcome. ## 3.9 Widened Types @@ -2247,7 +2247,7 @@ A signature is said to be an ***applicable signature*** with respect to an argum ### 4.12.2 Type Argument Inference -Given a signature < *T1* , *T2* , … , *Tn* > ( *p1* : *P1* , *p2* : *P2* , … , *pm* : *Pm* ), where each parameter type *P* references zero or more of the type parameters *T*, and an argument list ( *e1* , *e2* , … , *em* ), the task of type argument inference is to find a set of type arguments *A1*…*An* to substitute for *T1*…*Tn* such that the argument list becomes an applicable signature. +Given a signature < *T1* , *T2* , … , *Tn* > ( *p1* : *P1* , *p2* : *P2* , … , *pm* : *Pm* ), where each parameter type *P* references zero or more of the type parameters *T*, and an argument list ( *e1* , *e2* , … , *em* ), the task of type argument inference is to find a set of type arguments *A1*…*An* to substitute for *T1*…*Tn* such that the argument list becomes an applicable signature. The inferred type argument for a particular type parameter is determined from a set of candidate types. Given a type parameter *T*, let *C* denote the widened form (section [3.9](#3.9)) of the best common type (section [3.10](#3.10)) of the set of candidate types *T*. Then, @@ -2337,7 +2337,7 @@ The inclusion of type arguments in the *Arguments* production (section [4.12](#4 f(g(7)); ``` -could be interpreted as a call to ‘f’ with two arguments, ‘g < A’ and ‘B > (7)’. Alternatively, it could be interpreted as a call to ‘f’ with one argument, which is a call to a generic function ‘g’ with two type arguments and one regular argument. +could be interpreted as a call to ‘f’ with two arguments, ‘g < A’ and ‘B > (7)’. Alternatively, it could be interpreted as a call to ‘f’ with one argument, which is a call to a generic function ‘g’ with two type arguments and one regular argument. The grammar ambiguity is resolved as follows: In a context where one possible interpretation of a sequence of tokens is an *Arguments* production, if the initial sequence of tokens forms a syntactically correct *TypeArguments* production and is followed by a ‘`(`‘ token, then the sequence of tokens is processed an *Arguments* production, and any other possible interpretation is discarded. Otherwise, the sequence of tokens is not considered an *Arguments* production. @@ -2449,7 +2449,7 @@ In the example above, The subsections that follow specify the compile-time processing rules of the binary operators. In general, if the operands of a binary operator do not meet the stated requirements, a compile-time error occurs and the result of the operation defaults to type any in further processing. Tables that summarize the compile-time processing rules for operands of the Any type, the Boolean, Number, and String primitive types, and all object types and type parameters (the Object column in the tables) are provided. -### 4.15.1 The *, /, %, –, <<, >>, >>>, &, ^, and | operators +### 4.15.1 The *, /, %, –, <<, >>, >>>, &, ^, and | operators These operators require their operands to be of type Any, the Number primitive type, or an enum type. Operands of an enum type are treated as having the primitive type Number. If one operand is the `null` or `undefine``d` value, it is treated as having the type of the other operand. The result is always of the Number primitive type. @@ -2483,7 +2483,7 @@ var s = getValue() + ""; The example above converts the result of ‘getValue()’ to a string if it isn’t a string already. The type inferred for ‘s’ is the String primitive type regardless of the return type of ‘getValue’. -### 4.15.3 The <, >, <=, >=, ==, !=, ===, and !== operators +### 4.15.3 The <, >, <=, >=, ==, !=, ===, and !== operators These operators require one operand type to be identical to or a subtype of the other operand type. The result is always of the Boolean primitive type. @@ -4398,7 +4398,7 @@ The source elements permitted in a TypeScript implementation source file are a s Declaration source files are restricted to contain declarations only. Declaration source files can be used to declare the static type information associated with existing JavaScript code in an adjunct manner. They are entirely optional but enable the TypeScript compiler and tools to provide better verification and assistance when integrating existing JavaScript code and libraries in a TypeScript application. -Implementation and declaration source files that contain no import or export declarations form the single ***global module***. Entities declared in the global module are in scope everywhere in a program. Initialization order of the source files that make up the global module ultimately depends on the order in which the generated JavaScript files are loaded at run-time (which, for example, may be controlled by