Merge pull request #914 from Microsoft/parensInTypes

Parentheses in type literals

Author: ahejlsberg

Jakefile

@@ -279,7 +279,6 @@ 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);
 
@@ -292,7 +291,6 @@ compileFile(word2mdJs,
 
 // 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);

doc/TypeScript Language Specification (Change Markup).docx

@@ -1155,8 +1155,8 @@ For purposes of property access (section [4.10](#4.10)) and function calls ([4.1
 When used as a contextual type (section [4.19](#4.19)), a union type *U* has those members that are present in any of its constituent types, with types that are unions of the respective members in the constituent types. Specifically:
 
 * Let *S* be the set of types in *U* that has a property *P*. If *S* is not empty, *U* has a property *P* of a union type of the types of *P* from each type in *S*.
-* Let *S* be the set of types in *U* that have call signatures. If *S* is not empty and the sets of call signatures of the types in *S* are identical ignoring return types,* U* has the same set of call signatures, but with return types that are unions of the return types of the respective call signatures from each type in *S*.
-* Let *S* be the set of types in *U* that have construct signatures. If *S* is not empty and the sets of construct signatures of the types in *S* are identical ignoring return types,* U* has the same set of construct signatures, but with return types that are unions of the return types of the respective construct signatures from each type in *S*.
+* Let *S* be the set of types in *U* that have call signatures. If *S* is not empty and the sets of call signatures of the types in *S* are identical ignoring return types, *U* has the same set of call signatures, but with return types that are unions of the return types of the respective call signatures from each type in *S*.
+* Let *S* be the set of types in *U* that have construct signatures. If *S* is not empty and the sets of construct signatures of the types in *S* are identical ignoring return types, *U* has the same set of construct signatures, but with return types that are unions of the return types of the respective construct signatures from each type in *S*.
 * Let *S* be the set of types in *U* that has a string index signature. If *S* is not empty, *U* has a string index signature of a union type of the types of the string index signatures from each type in *S*.
 * Let *S* be the set of types in *U* that has a numeric index signature. If *S* is not empty, *U* has a numeric index signature of a union type of the types of the numeric index signatures from each type in *S*.
 
@@ -1349,16 +1349,33 @@ class G<T> {               // Introduce type parameter T
 Types are specified either by referencing their keyword or name, or by writing object type literals, array type literals, tuple type literals, function type literals, constructor type literals, or type queries.
 
 &emsp;&emsp;*Type:*  
+&emsp;&emsp;&emsp;*PrimaryOrUnionType*  
+&emsp;&emsp;&emsp;*FunctionType*  
+&emsp;&emsp;&emsp;*ConstructorType*
+
+&emsp;&emsp;*PrimaryOrUnionType:*  
+&emsp;&emsp;&emsp;*PrimaryType*  
+&emsp;&emsp;&emsp;*UnionType*
+
+&emsp;&emsp;*PrimaryType:*  
+&emsp;&emsp;&emsp;*ParenthesizedType*  
 &emsp;&emsp;&emsp;*PredefinedType*  
 &emsp;&emsp;&emsp;*TypeReference*  
 &emsp;&emsp;&emsp;*ObjectType*  
 &emsp;&emsp;&emsp;*ArrayType*  
 &emsp;&emsp;&emsp;*TupleType*  
-&emsp;&emsp;&emsp;*UnionType*  
-&emsp;&emsp;&emsp;*FunctionType*  
-&emsp;&emsp;&emsp;*ConstructorType*  
 &emsp;&emsp;&emsp;*TypeQuery*
 
+&emsp;&emsp;*ParenthesizedType:*  
+&emsp;&emsp;&emsp;`(`&emsp;*Type*&emsp;`)`
+
+Parentheses are required around union, function, or constructor types when they are used as array element types, and parentheses are required around function or constructor types in union types. For example:
+
+```TypeScript
+(string | number)[]  
+((x: string) => string) | (x: number) => number)
+```
+
 The different forms of type notations are described in the following sections.
 
 ### <a name="3.6.1"/>3.6.1 Predefined Types
@@ -1461,36 +1478,24 @@ The members of an object type literal are specified as a combination of property
 An array type literal is written as an element type followed by an open and close square bracket.
 
 &emsp;&emsp;*ArrayType:*  
-&emsp;&emsp;&emsp;*ElementType*&emsp;*[no LineTerminator here]*&emsp;`[`&emsp;`]`
-
-&emsp;&emsp;*ElementType:*  
-&emsp;&emsp;&emsp;*PredefinedType*  
-&emsp;&emsp;&emsp;*TypeReference*  
-&emsp;&emsp;&emsp;*ObjectType*  
-&emsp;&emsp;&emsp;*ArrayType*  
-&emsp;&emsp;&emsp;*TupleType*  
-&emsp;&emsp;&emsp;*TypeQuery*
+&emsp;&emsp;&emsp;*PrimaryType*&emsp;*[no LineTerminator here]*&emsp;`[`&emsp;`]`
 
 An array type literal references an array type (section [3.3.2](#3.3.2)) with the given element type. An array type literal is simply shorthand notation for a reference to the generic interface type 'Array' in the global module with the element type as a type argument.
 
-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 *UnionType*, *FunctionType* or *ConstructorType*. To use one of those forms for the element type, an array type must be written using the 'Array&lt;T>' notation. For example, the type
+When union, function, or constructor types are used as array element types they must be enclosed in parentheses. For example:
 
 ```TypeScript
-() => string[]
+(string | number)[]  
+(() => string))[]
 ```
 
-denotes a function returning a string array, not an array of functions returning string. The latter can be expressed using 'Array&lt;T>' notation
+Alternatively, array types can be written using the 'Array&lt;T>' notation. For example, the types above are equivalent to
 
 ```TypeScript
+Array<string | number>  
 Array<() => string>
 ```
 
-or by writing the element type as an object type literal
-
-```TypeScript
-{ (): string }[]
-```
-
 ### <a name="3.6.5"/>3.6.5 Tuple Type Literals
 
 A tuple type literal is written as a sequence of element types, separated by commas and enclosed in square brackets.
@@ -1512,28 +1517,22 @@ A tuple type literal references a tuple type (section [3.3.3](#3.3.3)).
 A union type literal is written as a sequence of types separated by vertical bars.
 
 &emsp;&emsp;*UnionType:*  
-&emsp;&emsp;&emsp;*ElementType*&emsp;`|`&emsp;*UnionOrElementType*
-
-&emsp;&emsp;*UnionOrElementType:*  
-&emsp;&emsp;&emsp;*UnionType*  
-&emsp;&emsp;&emsp;*ElementType*
+&emsp;&emsp;&emsp;*PrimaryOrUnionType*&emsp;`|`&emsp;*PrimaryType*
 
 A union typle literal references a union type (section [3.3.4](#3.3.4)).
 
-In order to avoid grammar ambiguities, union type literals permit only a restricted set of notations for the element types. Specifically, an element of a *UnionType* cannot be written as a *FunctionType* or *ConstructorType*. To include function or constructor types in a union type the function or constructor types must be written as object type literals. For example
+When function or constructor types are included in union types they must be enclosed in parentheses. For example:
 
 ```TypeScript
-() => string | () => number
+((x: string) => string) | ((x: number) => number)
 ```
 
-denotes a function whose return value is either a string or a function returning number, whereas
+Alternatively, function or constructor types in union types can be written using object literals:
 
 ```TypeScript
-{ (): string } | { (): number }
+{ (x: string): string } | { (x: number): number }
 ```
 
-denotes either a function returning string or a function returning number.
-
 ### <a name="3.6.7"/>3.6.7 Function Type Literals
 
 A function type literal specifies the type parameters, regular parameters, and return type of a call signature.
@@ -2221,8 +2220,8 @@ The resulting type an array literal expression is determined as follows:
 The rules above mean that an array literal is always of an array type, unless it is contextually typed by a type with numerically named properties (such as a tuple type). For example
 
 ```TypeScript
-var a = [1, 2];                          // Array<number>  
-var b = ["hello", true];                 // Array<string | boolean>  
+var a = [1, 2];                          // number[]  
+var b = ["hello", true];                 // (string | boolean)[]  
 var c: [number, string] = [3, "three"];  // [number, string]
 ```
 
@@ -5170,16 +5169,26 @@ This appendix contains a summary of the grammar found in the main document. As d
 &emsp;&emsp;&emsp;*Type*
 
 &emsp;&emsp;*Type:*  
+&emsp;&emsp;&emsp;*PrimaryOrUnionType*  
+&emsp;&emsp;&emsp;*FunctionType*  
+&emsp;&emsp;&emsp;*ConstructorType*
+
+&emsp;&emsp;*PrimaryOrUnionType:*  
+&emsp;&emsp;&emsp;*PrimaryType*  
+&emsp;&emsp;&emsp;*UnionType*
+
+&emsp;&emsp;*PrimaryType:*  
+&emsp;&emsp;&emsp;*ParenthesizedType*  
 &emsp;&emsp;&emsp;*PredefinedType*  
 &emsp;&emsp;&emsp;*TypeReference*  
 &emsp;&emsp;&emsp;*ObjectType*  
 &emsp;&emsp;&emsp;*ArrayType*  
 &emsp;&emsp;&emsp;*TupleType*  
-&emsp;&emsp;&emsp;*UnionType*  
-&emsp;&emsp;&emsp;*FunctionType*  
-&emsp;&emsp;&emsp;*ConstructorType*  
 &emsp;&emsp;&emsp;*TypeQuery*
 
+&emsp;&emsp;*ParenthesizedType:*  
+&emsp;&emsp;&emsp;`(`&emsp;*Type*&emsp;`)`
+
 &emsp;&emsp;*PredefinedType:*  
 &emsp;&emsp;&emsp;`any`  
 &emsp;&emsp;&emsp;`number`  
@@ -5216,15 +5225,7 @@ This appendix contains a summary of the grammar found in the main document. As d
 &emsp;&emsp;&emsp;*MethodSignature*
 
 &emsp;&emsp;*ArrayType:*  
-&emsp;&emsp;&emsp;*ElementType*&emsp;*[no LineTerminator here]*&emsp;`[`&emsp;`]`
-
-&emsp;&emsp;*ElementType:*  
-&emsp;&emsp;&emsp;*PredefinedType*  
-&emsp;&emsp;&emsp;*TypeReference*  
-&emsp;&emsp;&emsp;*ObjectType*  
-&emsp;&emsp;&emsp;*ArrayType*  
-&emsp;&emsp;&emsp;*TupleType*  
-&emsp;&emsp;&emsp;*TypeQuery*
+&emsp;&emsp;&emsp;*PrimaryType*&emsp;*[no LineTerminator here]*&emsp;`[`&emsp;`]`
 
 &emsp;&emsp;*TupleType:*  
 &emsp;&emsp;&emsp;`[`&emsp;*TupleElementTypes*&emsp;`]`
@@ -5237,11 +5238,7 @@ This appendix contains a summary of the grammar found in the main document. As d
 &emsp;&emsp;&emsp;*Type*
 
 &emsp;&emsp;*UnionType:*  
-&emsp;&emsp;&emsp;*ElementType*&emsp;`|`&emsp;*UnionOrElementType*
-
-&emsp;&emsp;*UnionOrElementType:*  
-&emsp;&emsp;&emsp;*UnionType*  
-&emsp;&emsp;&emsp;*ElementType*
+&emsp;&emsp;&emsp;*PrimaryOrUnionType*&emsp;`|`&emsp;*PrimaryType*
 
 &emsp;&emsp;*FunctionType:*  
 &emsp;&emsp;&emsp;*TypeParameters<sub>opt</sub>*&emsp;`(`&emsp;*ParameterList<sub>opt</sub>*&emsp;`)`&emsp;`=>`&emsp;*Type*