Live -> master

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-##How to contribute
+## How to contribute
 If you'd like to contribute to the F# documentation, all you need to do is:
 
 1. [Clone the documentation repo](https://help.github.com/articles/cloning-a-repository/)

docs/conceptual/array.maxby['t,'u]-function-[fsharp].md

@@ -47,7 +47,8 @@ Returns the maximum element.
 
 ## Remarks
 
-This function is named `MaxBy` in compiled assemblies. If you are accessing the function from a language other than F#, or through reflection, use this name.
+This function is named `MaxBy` in compiled assemblies. If you are accessing the function from a language other than F#, or through reflection, use this name.  
+Ties are resolved by returning the element with the lowest ordinal.  
 
 ## Example
 
@@ -75,4 +76,4 @@ Supported in: 2.0, 4.0, Portable
 
 [Collections.Array Module (F#)](Collections.Array-Module-%5BFSharp%5D.md)
 
-[Microsoft.FSharp.Collections Namespace (F#)](Microsoft.FSharp.Collections-Namespace-%5BFSharp%5D.md)
+[Microsoft.FSharp.Collections Namespace (F#)](Microsoft.FSharp.Collections-Namespace-%5BFSharp%5D.md)

docs/conceptual/array2d.init['t]-function-[fsharp].md

@@ -54,7 +54,7 @@ Returns the generated array.
 
 This function is named `Initialize` in compiled assemblies. If you are accessing the function from a language other than F#, or through reflection, use this name.
 
-## Examxample
+## Example
 
 The following code demonstrates the use of `Array2D.init` to create a two-dimensional array.
 
@@ -74,4 +74,4 @@ Supported in: 2.0, 4.0, Portable
 
 [Collections.Array2D Module (F#)](Collections.Array2D-Module-%5BFSharp%5D.md)
 
-[Microsoft.FSharp.Collections Namespace (F#)](Microsoft.FSharp.Collections-Namespace-%5BFSharp%5D.md)
+[Microsoft.FSharp.Collections Namespace (F#)](Microsoft.FSharp.Collections-Namespace-%5BFSharp%5D.md)

docs/conceptual/async.startchild['t]-method-[fsharp].md

@@ -65,6 +65,8 @@ let! result2 = completor2
 
 When used in this way, each use of `StartChild` starts an instance of `childComputation` and returns a `completor` object representing a computation to wait for the completion of the operation. When executed, the `completor` awaits the completion of `childComputation`.
 
+If child computation doesn't complete in the specified timeout period, the `childComputation` is cancelled and the `completor` raises [`System.TimeoutException`](https://msdn.microsoft.com/en-us/library/system.timeoutexception).
+
 ## Example
 
 The following code example illustrates the use of `Async.StartChild`.

docs/conceptual/collections.array-module-[fsharp].md

@@ -43,7 +43,7 @@ For an overview of arrays in F#, see [Arrays (F#)](Arrays-%5BFSharp%
 |[`compareWith`](array.comparewith%5B't%5D-function-%5Bfsharp%5D.md)<br />**: ('T -&gt; 'T -&gt; int) -&gt; 'T [] -&gt; 'T [] -&gt; int**|Compares two arrays using the given comparison function, element by element.|
 |[`concat`](https://msdn.microsoft.com/library/f7219b79-1ec8-4a25-96b1-edbedb358302)<br />**: seq&lt;'T []&gt; -&gt; 'T []**|Creates an array that contains the elements of each of the supplied sequence of arrays.|
 |[`contains`](array.contains%5B't%5D-function-%5Bfsharp%5D.md)<br />**: 'T -&gt; 'T [] -&gt; bool**|Evaluates to `true` if the given element is in the input array.|
-|[`copy`](https://msdn.microsoft.com/library/9d0202f1-1ea0-475e-9d66-4f8ccc3c5b5f)<br />**: 'T -&gt; 'T []**|Creates an array that contains the elements of the supplied array.|
+|[`copy`](https://msdn.microsoft.com/library/9d0202f1-1ea0-475e-9d66-4f8ccc3c5b5f)<br />**: 'T [] -&gt; 'T []**|Creates an array that contains the elements of the supplied array.|
 |[`countBy`](array.countby['t,'key]-function-[fsharp].md)<br />**: ('T -&gt; 'Key) -&gt; 'T [] -&gt; ('Key &#42; int) []**|Applies a key-generating function to each element of an array and returns am array yielding unique keys and their number of occurrences in the original array.|
 |[`create`](https://msdn.microsoft.com/library/e848c8d6-1142-4080-9727-8dacc26066be)<br />**: int -&gt; 'T -&gt; 'T []**|Creates an array whose elements are all initially the supplied value.|
 |[`distinct`](array.distinct%5B't%5D-function-%5Bfsharp%5D.md)<br />**: 'T [] -&gt; 'T []**|Returns an array that contains no duplicate entries according to generic hash and equality comparisons on the entries. If an element occurs multiple times in the array then the later occurrences are discarded.|

docs/conceptual/collections.list-module-[fsharp].md

@@ -41,13 +41,14 @@ For an overview of lists in F#, see [Lists (F#)](Lists-%5BFSharp%5D.
 |[choose](https://msdn.microsoft.com/library/2e21d3fb-ce35-4824-8a57-c4404616093d)<br />**: ('T -&gt; 'U option) -&gt; 'T list -&gt; 'U list**|Applies the given function to each element of the list. Returns the list comprised of the results for each element where the function returns **Some**.|
 |[chunkBySize](list.chunkBySize%5B't%5D-function-%5Bfsharp%5D.md)<br />**: int -&gt; 'T list -&gt; 'T list list**|Divides the input list into chunks of size at most `chunkSize`.|
 |[collect](https://msdn.microsoft.com/library/cd08bbc7-a3b9-40ab-8c20-4e85ec84664f)<br />**: ('T -&gt; 'U list) -&gt; 'T list -&gt; 'U list**|For each element of the list, applies the given function. Concatenates all the results and return the combined list.|
-|[comparewith](list.comparewith%5B't%5D-function-%5Bfsharp%5D.md)<br />**: ('T -&gt; 'T -&gt; int) -&gt; 'T list -&gt; 'T list -&gt; int**|Compares two lists using the given comparison function, element by element.|
+|[compareWith](list.compareWith%5B't%5D-function-%5Bfsharp%5D.md)<br />**: ('T -&gt; 'T -&gt; int) -&gt; 'T list -&gt; 'T list -&gt; int**|Compares two lists using the given comparison function, element by element.|
 |[concat](https://msdn.microsoft.com/library/c5afd433-8764-4ea8-a6a8-937fb4d77c4c)<br />**: seq&lt;'T list&gt; -&gt; 'T list**|Returns a new list that contains the elements of each the lists in order.|
 |[contains](list.contains%5B't%5D-function-%5Bfsharp%5D.md)<br />**: 'T -&gt; 'T list -&gt; bool**|Evaluates to `true` if the given element is in the input list.|
 |[countBy](list.countby%5B't,'key%5D-function-%5Bfsharp%5D.md)<br />**: ('T -&gt; 'Key) -&gt; 'T list -&gt; ('Key &#42; int) list**|Applies a key-generating function to each element of a list and returns a list yielding unique keys and their number of occurrences in the original list.|
 |[distinct](list.distinct%5B't%5D-function-%5Bfsharp%5D.md)<br />**: 'T -&gt; 'T list**|Returns a list that contains no duplicate entries according to generic hash and equality comparisons on the entries. If an element occurs multiple times in the list then the later occurrences are discarded.|
 |[distinctBy](https://msdn.microsoft.com/library/9293293b-9420-49c8-848f-401a9cd49b75)<br />**: ('T -&gt; 'Key) -&gt; 'T list -&gt; 'T list**|Returns a list that contains no duplicate entries according to the generic hash and equality comparisons on the keys returned by the given key-generating function. If an element occurs multiple times in the list then the later occurrences are discarded.|
 |[empty](https://msdn.microsoft.com/library/bb4cb501-3429-47c1-8d5f-71180d3bded7)<br />**: 'T list**|Returns an empty list of the given type.|
+|[except](https://github.com/fsharp/fslang-design/issues/41)<br />**: seq&lt;'T&gt; -&gt; 'T list -&gt; 'T list**|Returns a list with the distinct elements of the input list which do not appear in the itemsToExclude sequence, using generic hash and equality comparisons to compare values.|
 |[exactlyOne](https://msdn.microsoft.com/library/bd14fd21-b645-4416-98e4-6a6c49f3a15c)<br />**: 'T list -&gt; 'T**|Returns the only element of the list.|
 |[exists](https://msdn.microsoft.com/library/15a3ebd5-98f0-44c0-8220-7dedec3e68a8)<br />**: ('T -&gt; bool) -&gt; 'T list -&gt; bool**|Tests if any element of the list satisfies the given predicate.|
 |[exists2](https://msdn.microsoft.com/library/7532b39e-3f4f-4534-a60b-d7721dc6fa7e)<br />**: ('T1 -&gt; 'T2 -&gt; bool) -&gt; 'T1 list -&gt; 'T2 list -&gt; bool**|Tests if any pair of corresponding elements of the lists satisfies the given predicate.|

docs/conceptual/core.customoperationattribute-class-[fsharp].md

@@ -36,13 +36,8 @@ CustomOperationAttribute
   member this.IsLikeZip : bool with get, set
   member this.MaintainsVariableSpace : bool with get, set
   member this.MaintainsVariableSpaceUsingBind : bool with get, set
-  member this.Name : string
-  member this.IsLikeGroupJoin : bool with get, set
-  member this.IsLikeJoin : bool with get, set
-  member this.IsLikeZip : bool with get, set
   member this.JoinConditionWord : string with get, set
-  member this.MaintainsVariableSpace : bool with get, set
-  member this.MaintainsVariableSpaceUsingBind  : bool with get, set
+  member this.Name : string
  end
 ```
 

docs/conceptual/core.operators-module-[fsharp].md

@@ -76,7 +76,7 @@ For an overview of operators in F#, see [Symbol and Operator Reference (F&#3
 |[( &#124;&#124;&gt; )](https://msdn.microsoft.com/library/6018719e-de1a-4d1f-8f91-88a35a4f0e8e)<br />**: 'T1 &#42; 'T2 -&gt; ('T1 -&gt; 'T2 -&gt; 'U) -&gt; 'U**|Apply a function to two values, the values being a pair on the left, the function on the right.|
 |[( &#124;&#124;&#124; )](https://msdn.microsoft.com/library/69f82f6e-98f3-468c-b5cd-a0b4b411ddb2)<br />**: ^T -&gt; ^T -&gt; ^T**|Overloaded bitwise OR operator|
 |[( &#124;&#124;&#124;&gt; )](https://msdn.microsoft.com/library/0b5a6221-904a-4cf8-9fd4-ad5a4ec3817b)<br />**: 'T1 &#42; 'T2 &#42; 'T3 -&gt; ('T1 -&gt; 'T2 -&gt; 'T3 -&gt; 'U) -&gt; 'U**|Apply a function to three values, the values being a triple on the left, the function on the right.|
-|[( ~- )](https://msdn.microsoft.com/library/f6c4a5ca-7803-49d2-85fa-0ac3e0c2b3eb)<br />**: ^T -&gt; ^T**|Overloaded prefix plus operator.|
+|[( ~+ )](https://msdn.microsoft.com/library/f6c4a5ca-7803-49d2-85fa-0ac3e0c2b3eb)<br />**: ^T -&gt; ^T**|Overloaded prefix plus operator.|
 |[( ~- )](https://msdn.microsoft.com/library/8350b9b2-2f8c-4fd5-8c81-afacc5196d14)<br />**: ^T -&gt; ^T**|Overloaded unary negation.|
 |[( ~~~ )](https://msdn.microsoft.com/library/80822c6d-b0a8-445c-adbc-2dd78954cc5d)<br />**: ^T -&gt; ^T**|Overloaded bitwise NOT operator.|
 |[abs](https://msdn.microsoft.com/library/9cf0a350-111e-45df-a2d0-306884aeb937)<br />**: ^T -&gt; ^T**|Absolute value of the given number.|
@@ -172,4 +172,4 @@ Windows 8, Windows 7, Windows Server 2012, Windows Server 2008 R2
 Supported in: 2.0, 4.0, Portable
 
 ## See Also
-[Microsoft.FSharp.Core Namespace &#40;F&#35;&#41;](Microsoft.FSharp.Core-Namespace-%5BFSharp%5D.md)
+[Microsoft.FSharp.Core Namespace &#40;F&#35;&#41;](Microsoft.FSharp.Core-Namespace-%5BFSharp%5D.md)

docs/conceptual/core.printf-module-[fsharp].md

@@ -53,9 +53,8 @@ The optional *width* is an integer indicating the minimal width of the result. F
 Valid flags are described in the following table.
 
 
-
-||
-|-|
+|Flag|Description|
+|----|-----------|
 |`0`|Specifies to add zeros instead of spaces to make up the required width.|
 |`-`|Specifies to left-justify the result within the width specified.|
 |`+`|Specifies to add a `+` character if the number is positive (to match a `-` sign for negative numbers).|
@@ -104,4 +103,4 @@ Supported in: 2.0, 4.0, Portable
 Supported in: 2, 3
 
 ## See Also
-[Microsoft.FSharp.Core Namespace (F#)](Microsoft.FSharp.Core-Namespace-%5BFSharp%5D.md)
+[Microsoft.FSharp.Core Namespace (F#)](Microsoft.FSharp.Core-Namespace-%5BFSharp%5D.md)

docs/conceptual/list.exists2['t1,'t2]-function-[fsharp].md

@@ -13,7 +13,7 @@ ms.assetid: 09474659-eff2-4903-bdbd-967f65f00f17
 
 # List.exists2<'T1,'T2> Function (F#)
 
-Tests if any pair of corresponding elements of the lists satisfies the given predicate.
+Tests if any pair of corresponding elements of the lists satisfies the given predicate. The lists must have equal lengths.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 
@@ -55,8 +55,14 @@ The second input list.
 
 `true` if any pair of elements satisfy the predicate. Otherwise, returns `false`.
 
+## Exceptions
+
+|Exception|Condition|
+|----|----|
+|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the input lists differ in length.|
+
 ## Remarks
-The predicate is applied to matching elements in the two collections up to the lesser of the two lengths of the collections. If any application returns true then the overall result is true and no further elements are tested.
+The predicate is applied to matching elements in the two collections. If any application returns true then the overall result is true and no further elements are tested.
 
 This function is named `Exists2` in compiled assemblies. If you are accessing the function from a .NET language other than F#, or through reflection, use this name.
 

docs/conceptual/list.fold2['t1,'t2,'state]-function-[fsharp].md

@@ -13,7 +13,8 @@ ms.assetid: 3c8edaf5-fbbb-4726-900e-b2423c54caf0
 
 # List.fold2<'T1,'T2,'State> Function (F#)
 
-Applies a function to corresponding elements of two collections, threading an accumulator argument through the computation. The collections must have identical sizes. If the input function is `f` and the elements are `i0...iN` and `j0...jN` then computes `f (... (f s i0 j0)...) iN jN`.
+Applies a function to corresponding elements of two lists, threading an accumulator argument through the computation. The lists must have equal lengths.
+If the input function is `f` and the elements are `i0...iN` and `j0...jN` then computes `f (... (f s i0 j0)...) iN jN`.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 
@@ -58,16 +59,16 @@ Type: **'T2**[list](https://msdn.microsoft.com/library/c627b668-477b-4409-91ed-0
 
 The second input list.
 
+## Return Value
+
+The final state value.
+
 ## Exceptions
 
 |Exception|Condition|
 |----|----|
 |[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the input lists differ in length.|
 
-## Return Value
-
-The final state value.
-
 ## Remarks
 This function is named `Fold2` in compiled assemblies. If you are accessing the function from a .NET language other than F#, or through reflection, use this name.
 

docs/conceptual/list.foldback2['t1,'t2,'state]-function-[fsharp].md

@@ -13,7 +13,8 @@ ms.assetid: 5b84c2a5-18db-44dc-9c5c-f83664672e45
 
 # List.foldBack2<'T1,'T2,'State> Function (F#)
 
-Applies a function to corresponding elements of two collections, threading an accumulator argument through the computation. The collections must have identical sizes. If the input function is `f` and the elements are `i0...iN` and `j0...jN`, then this function computes `f i0 j0 (...(f iN jN s))`.
+Applies a function to corresponding elements of two lists, threading an accumulator argument through the computation. The lists must have equal lengths.
+If the input function is `f` and the elements are `i0...iN` and `j0...jN`, then this function computes `f i0 j0 (...(f iN jN s))`.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 
@@ -58,16 +59,15 @@ Type: **'State**
 
 The initial state.
 
+## Return Value
+
+The final state value.
 
 ## Exceptions
 
 |Exception|Condition|
 |----|----|
-|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the list is empty.|
-
-## Return Value
-
-The final state value.
+|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the lists differ in length.|
 
 ## Remarks
 This function is named `FoldBack2` in compiled assemblies. If you are accessing the function from a .NET language other than F#, or through reflection, use this name.

docs/conceptual/list.forall2['t1,'t2]-function-[fsharp].md

@@ -13,7 +13,7 @@ ms.assetid: a125b984-5e21-4dc4-9734-b0b796807401
 
 # List.forall2<'T1,'T2> Function (F#)
 
-Tests if all corresponding elements of the collection satisfy the given predicate pairwise.
+Tests if all corresponding elements of the lists satisfy the given predicate pairwise. The lists must have equal lengths.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 

docs/conceptual/list.iter2['t1,'t2]-function-[fsharp].md

@@ -13,7 +13,7 @@ ms.assetid: 54b3700b-9b7a-46be-8dba-fbdeef5b5353
 
 # List.iter2<'T1,'T2> Function (F#)
 
-Applies the given function to two collections simultaneously. The collections must have identical size.
+Applies the given function to two lists simultaneously. The lists must have equal lengths.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 

docs/conceptual/list.iteri2['t1,'t2]-function-[fsharp].md

@@ -13,7 +13,7 @@ ms.assetid: 183c14eb-67b1-4550-a5ec-a417a61261a9
 
 # List.iteri2<'T1,'T2> Function (F#)
 
-Applies the given function to two collections simultaneously. The collections must have identical size. The integer passed to the function indicates the index of element.
+Applies the given function to two lists simultaneously. The lists must have equal lengths. The integer passed to the function indicates the index of element.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 

docs/conceptual/list.map2['t1,'t2,'u]-function-[fsharp].md

@@ -13,7 +13,7 @@ ms.assetid: aa680673-f521-47b3-bd42-29a526d93904
 
 # List.map2<'T1,'T2,'U> Function (F#)
 
-Creates a new collection whose elements are the results of applying the given function to the corresponding elements of the two collections pairwise.
+Creates a new list whose elements are the results of applying the given function to the corresponding elements of the two lists pairwise. The lists must have equal lengths.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 
@@ -55,6 +55,12 @@ The second input list.
 
 The list of resulting elements.
 
+## Exceptions
+
+|Exception|Condition|
+|----|----|
+|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the input lists differ in length.|
+
 ## Remarks
 The two lists *list1* and *list2* must have the same length. If they don't, an exception is thrown.
 

docs/conceptual/list.map3['t1,'t2,'t3,'u]-function-[fsharp].md

@@ -13,7 +13,7 @@ ms.assetid: 4ebaa36f-1162-419f-ba5e-18f851a63c01
 
 # List.map3<'T1,'T2,'T3,'U> Function (F#)
 
-Creates a new collection whose elements are the results of applying the given function to the corresponding elements of the three collections simultaneously.
+Creates a new list whose elements are the results of applying the given function to the corresponding elements of the three lists simultaneously. The lists must have equal lengths.
 
 **Namespace/Module Path**: Microsoft.FSharp.Collections.List
 
@@ -60,9 +60,15 @@ The third input list.
 
 ## Return Value
 
-he list of transformed elements.
+The list of transformed elements.
+
+## Exceptions
+
+|Exception|Condition|
+|----|----|
+|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the input lists differ in length.|
+
 ## Remarks
-The three lists *list1*, *list2*, and *list3* must all have the same length. If they don't, an exception is thrown.
 
 This function is named `Map3` in compiled assemblies. If you are accessing the function from a .NET language other than F#, or through reflection, use this name.
 

docs/conceptual/list.mapi2['t1,'t2,'u]-function-[fsharp].md

@@ -13,7 +13,7 @@ ms.assetid: 18316575-2a76-4312-a934-818bebb4ae3a
 
 # List.mapi2<'T1,'T2,'U> Function (F#)
 
-Like [`List.mapi`](https://msdn.microsoft.com/library/284b9234-3d26-409b-b328-ac79638d9e14), but mapping corresponding elements from two lists of equal length.
+Like [`List.mapi`](https://msdn.microsoft.com/library/284b9234-3d26-409b-b328-ac79638d9e14), but mapping corresponding elements from two lists. The lists must have equal lengths.
 
 **Namespace/Module Path:** Microsoft.FSharp.Collections.List
 
@@ -55,6 +55,12 @@ The second input list.
 
 The list of transformed elements.
 
+## Exceptions
+
+|Exception|Condition|
+|----|----|
+|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the input lists differ in length.|
+
 ## Remarks
 
 This function is named `MapIndexed2` in compiled assemblies. If you are accessing the function from a language other than F#, or through reflection, use this name.

docs/conceptual/list.zip3['t1,'t2,'t3]-function-[fsharp].md

@@ -55,6 +55,12 @@ The third input list.
 
 A single list containing triples of matching elements from the input lists.
 
+## Exceptions
+
+|Exception|Condition|
+|----|----|
+|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)|Thrown when the input lists differ in length.|
+
 ## Remarks
 
 This function is named `Zip3` in compiled assemblies. If you are accessing the function from a language other than F#, or through reflection, use this name.