👓 sweep docset for areas where in wasn't mentioned but should be

docs/csharp/lambda-expressions.md

@@ -146,7 +146,7 @@ Lambdas can refer to *outer variables* (see [Anonymous methods](programming-guid
 
 - Variables introduced within a lambda expression are not visible in the outer method.
 
-- A lambda expression cannot directly capture a `ref` or `out` parameter from an enclosing method.
+- A lambda expression cannot directly capture an `in`, `ref`, or `out` parameter from an enclosing method.
 
 - A return statement in a lambda expression does not cause the enclosing method to return.
 

docs/csharp/language-reference/keywords/async.md

@@ -73,7 +73,7 @@ An async method can have the following return types:
 - [void](../../../csharp/language-reference/keywords/void.md), which should only be used for event handlers.
 - Starting with C# 7, any type that has an accessible `GetAwaiter` method. The `System.Threading.Tasks.ValueTask<TResult>` type is one such implementation. It is available by adding the NuGet package `System.Threading.Tasks.Extensions`. 
 
-The async method can't declare any [ref](../../../csharp/language-reference/keywords/ref.md) or [out](../../../csharp/language-reference/keywords/out.md) parameters, nor can it have a <!-- [reference return value](../../programming-guide/classes-and-structs/ref-returns.md) -->reference return value, but it can call methods that have such parameters.  
+The async method can't declare any [in](../../../csharp/language-reference/keywords/in-parameter-modifier.md), [ref](../../../csharp/language-reference/keywords/ref.md) or [out](../../../csharp/language-reference/keywords/out-parameter-modifier.md) parameters, nor can it have a [reference return value](../../programming-guide/classes-and-structs/ref-returns.md), but it can call methods that have such parameters.  
 
 You specify `Task<TResult>` as the return type of an async method if the [return](../../../csharp/language-reference/keywords/return.md) statement of the method specifies an operand of type `TResult`. You use `Task` if no meaningful value is returned when the method is completed. That is, a call to the method returns a `Task`, but when the `Task` is completed, any `await` expression that's awaiting the `Task` evaluates to `void`.  
 

docs/csharp/language-reference/keywords/in-generic-modifier.md

@@ -8,30 +8,32 @@ ms.topic: "article"
 helpviewer_keywords: 
   - "contravariance, in keyword [C#]"
   - "in keyword [C#]"
-ms.assetid: 3a778c36-8aed-4ebe-aa8b-39f4057215b1
-caps.latest.revision: 17
 author: "BillWagner"
 ms.author: "wiwagn"
 ---
+
 # in (Generic Modifier) (C# Reference)
+
 For generic type parameters, the `in` keyword specifies that the type parameter is contravariant. You can use the `in` keyword in generic interfaces and delegates.  
 
  Contravariance enables you to use a less derived type than that specified by the generic parameter. This allows for implicit conversion of classes that implement variant interfaces and implicit conversion of delegate types. Covariance and contravariance in generic type parameters are supported for reference types, but they are not supported for value types.  
 
- A type can be declared contravariant in a generic interface or delegate if it is used only as a type of method arguments and not used as a method return type. `Ref` and `out` parameters cannot be variant.  
+ A type can be declared contravariant in a generic interface or delegate only if it defines the type of a method's parameters and not of a method's return type. `In`, `ref`, and `out` parameters must be invariant, meaning they are neither covariant or contravariant.
 
- An interface that has a contravariant type parameter allows its methods to accept arguments of less derived types than those specified by the interface type parameter. For example, because in .NET Framework 4, in the <xref:System.Collections.Generic.IComparer%601> interface, type T is contravariant, you can assign an object of the `IComparer(Of Person)` type to an object of the `IComparer(Of Employee)` type without using any special conversion methods if `Employee` inherits `Person`.  
+ An interface that has a contravariant type parameter allows its methods to accept arguments of less derived types than those specified by the interface type parameter. For example, in the <xref:System.Collections.Generic.IComparer%601> interface, type T is contravariant, you can assign an object of the `IComparer<Person>` type to an object of the `IComparer<Employee>` type without using any special conversion methods if `Employee` inherits `Person`.  
 
  A contravariant delegate can be assigned another delegate of the same type, but with a less derived generic type parameter.  
 
  For more information, see [Covariance and Contravariance](../../programming-guide/concepts/covariance-contravariance/index.md).  
 
-## Example  
+## Contravariant generic interface   
+
  The following example shows how to declare, extend, and implement a contravariant generic interface. It also shows how you can use implicit conversion for classes that implement this interface.  
 
  [!code-csharp[csVarianceKeywords#1](../../../csharp/language-reference/keywords/codesnippet/CSharp/in-generic-modifier_1.cs)]  
 
-## Example  
+## Contravariant generic delegate  
+
  The following example shows how to declare, instantiate, and invoke a contravariant generic delegate. It also shows how you can implicitly convert a delegate type.  
 
  [!code-csharp[csVarianceKeywords#2](../../../csharp/language-reference/keywords/codesnippet/CSharp/in-generic-modifier_2.cs)]  
@@ -42,4 +44,4 @@ For generic type parameters, the `in` keyword specifies that the type parameter
 ## See Also  
  [out](../../../csharp/language-reference/keywords/out-generic-modifier.md)  
  [Covariance and Contravariance](../../programming-guide/concepts/covariance-contravariance/index.md)  
- [Modifiers](../../../csharp/language-reference/keywords/modifiers.md)
+ [Modifiers](../../../csharp/language-reference/keywords/modifiers.md)  

docs/csharp/language-reference/keywords/in-parameter-modifier.md

@@ -0,0 +1,68 @@
+---
+title: "in parameter modifier (C# Reference)"
+ms.date: 03/06/2018
+ms.prod: .net
+ms.technology: 
+  - "devlang-csharp"
+ms.topic: "article"
+helpviewer_keywords: 
+  - "parameters [C#], in"
+  - "in parameters [C#]"
+author: "BillWagner"
+ms.author: "wiwagn"
+---
+
+# in parameter modifier (C# Reference)
+
+The `in` keyword causes arguments to be passed by reference. It is like the [ref](ref.md) or [out](out-parameter-modifier.md) keywords, except that `in` arguments cannot be modified by the called method, whereas `ref` arguments may be modified,  `out` arguments must be modified by the caller, and those modifications are observable in the calling context.
+
+[!code-csharp-interactive[cs-in-keyword](../../../../samples/snippets/csharp/language-reference/keywords/in-ref-out-modifier/InParameterModifier.cs#1)]  
+
+The preceding example demonstrates that the `in` modifier is unnecessary at the call site. It is only required in the method declaration.
+
+> [!NOTE] 
+> The `in` keyword can also be used with a generic type parameter to specify that the type parameter is contravariant, as part of a `foreach` statement, or as part of a `join` clause in a LINQ query. For more information on the use of the `in` keyword in these contexts, see [in](in.md) which provides links to all those uses.
+
+ Variables passed as `in` arguments must be initialized before being passed in a method call. However, the called method may not assign a value or modify the argument.  
+
+ Although the `in`, `ref`, and `out` keywords cause different run-time behavior, they are not considered part of the method signature at compile time. Therefore, methods cannot be overloaded if the only difference is that one method takes a `ref` or `in` argument and the other takes an `out` argument. The following code, for example, will not compile:  
+
+```csharp
+class CS0663_Example
+{
+    // Compiler error CS0663: "Cannot define overloaded 
+    // methods that differ only on in, ref and out".
+    public void SampleMethod(in int i) { }
+    public void SampleMethod(ref int i) { }
+}
+```
+
+Overloading based on the presence of `in` is allowed, but generates a compiler warning:  
+
+```csharp
+class InOverloads
+{
+    // Discouraged. Calling SampleMethod(value) is ambiguous.
+    public void SampleMethod(in int i) { }
+    public void SampleMethod(int i) { }
+}
+```
+
+Properties or constants may be passed as `in` parameters, because the calling method may not modify their values.
+
+You can't use the `in`, `ref`, and `out` keywords for the following kinds of methods:  
+
+- Async methods, which you define by using the [async](../../../csharp/language-reference/keywords/async.md) modifier.  
+
+- Iterator methods, which include a [yield return](../../../csharp/language-reference/keywords/yield.md) or `yield break` statement.  
+
+You typically declare `in` arguments to avoid the copy operations necessary for passing arguments by value. This is most useful when arguments are structures or arrays of structures.
+
+## C# Language Specification  
+ [!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)]  
+
+## See Also  
+ [C# Reference](../../../csharp/language-reference/index.md)  
+ [C# Programming Guide](../../../csharp/programming-guide/index.md)  
+ [C# Keywords](../../../csharp/language-reference/keywords/index.md)  
+ [Method Parameters](../../../csharp/language-reference/keywords/method-parameters.md)

docs/csharp/language-reference/keywords/in.md

@@ -1,6 +1,6 @@
 ---
 title: "in (C# Reference)"
-ms.date: 07/20/2015
+ms.date: 02/06/2018
 ms.prod: .net
 ms.technology: 
   - "devlang-csharp"
@@ -10,19 +10,19 @@ f1_keywords:
   - "in_CSharpKeyword"
 helpviewer_keywords: 
   - "in keyword [C#]"
-ms.assetid: 52032838-0a38-476e-b4d5-94b59141952f
-caps.latest.revision: 9
 author: "BillWagner"
 ms.author: "wiwagn"
 ---
+
 # in (C# Reference)
-The `in` contextual keyword is used in three contexts:  
+
+The `in` contextual keyword is used in four contexts:  
 
--   [foreach](../../../csharp/language-reference/keywords/foreach-in.md) statements  
-
--   [join clauses](../../../csharp/language-reference/keywords/join-clause.md) in query expressions  
-
--   [generic type parameters](../../../csharp/language-reference/keywords/in-generic-modifier.md) in generic interfaces and delegates.  
+-   [generic type parameters](in-generic-modifier.md) in generic interfaces and delegates.
+-   As a [parameter modifier](in-parameter-modifier.md), which lets you pass an argument to a method by reference rather than by value.
+-   [foreach](foreach-in.md) statements.
+-   [join clauses](join-clause.md) in LINQ query expressions.
 
 ## See Also  
- [C# Reference](../../../csharp/language-reference/index.md)
+ [C# Keywords](index.md)  
+ [C# Reference](../index.md)

docs/csharp/language-reference/keywords/index.md

@@ -32,18 +32,18 @@ Keywords are predefined, reserved identifiers that have special meanings to the
 |[event](../../../csharp/language-reference/keywords/event.md)|[explicit](../../../csharp/language-reference/keywords/explicit.md)|[extern](../../../csharp/language-reference/keywords/extern.md)|[false](../../../csharp/language-reference/keywords/false.md)|  
 |[finally](../../../csharp/language-reference/keywords/try-finally.md)|[fixed](../../../csharp/language-reference/keywords/fixed-statement.md)|[float](../../../csharp/language-reference/keywords/float.md)|[for](../../../csharp/language-reference/keywords/for.md)|  
 |[foreach](../../../csharp/language-reference/keywords/foreach-in.md)|[goto](../../../csharp/language-reference/keywords/goto.md)|[if](../../../csharp/language-reference/keywords/if-else.md)|[implicit](../../../csharp/language-reference/keywords/implicit.md)|  
-|[in](../../../csharp/language-reference/keywords/foreach-in.md)|[in (generic modifier)](../../../csharp/language-reference/keywords/in-generic-modifier.md)|[int](../../../csharp/language-reference/keywords/int.md)|[interface](../../../csharp/language-reference/keywords/interface.md)|  
-|[internal](../../../csharp/language-reference/keywords/internal.md)|[is](../../../csharp/language-reference/keywords/is.md)|[lock](../../../csharp/language-reference/keywords/lock-statement.md)|[long](../../../csharp/language-reference/keywords/long.md)|
-|[namespace](../../../csharp/language-reference/keywords/namespace.md)|[new](../../../csharp/language-reference/keywords/new.md)|[null](../../../csharp/language-reference/keywords/null.md)|[object](../../../csharp/language-reference/keywords/object.md)|
-[operator](../../../csharp/language-reference/keywords/operator.md)|[out](../../../csharp/language-reference/keywords/out.md)|[out (generic modifier)](../../../csharp/language-reference/keywords/out-generic-modifier.md)|[override](../../../csharp/language-reference/keywords/override.md)|
-|[params](../../../csharp/language-reference/keywords/params.md)|[private](../../../csharp/language-reference/keywords/private.md)|[protected](../../../csharp/language-reference/keywords/protected.md)|[public](../../../csharp/language-reference/keywords/public.md)|
-|[readonly](../../../csharp/language-reference/keywords/readonly.md)|[ref](../../../csharp/language-reference/keywords/ref.md)|[return](../../../csharp/language-reference/keywords/return.md)|[sbyte](../../../csharp/language-reference/keywords/sbyte.md)|
-|[sealed](../../../csharp/language-reference/keywords/sealed.md)|[short](../../../csharp/language-reference/keywords/short.md)|[sizeof](../../../csharp/language-reference/keywords/sizeof.md)|[stackalloc](../../../csharp/language-reference/keywords/stackalloc.md)|
-|[static](../../../csharp/language-reference/keywords/static.md)|[string](../../../csharp/language-reference/keywords/string.md)|[struct](../../../csharp/language-reference/keywords/struct.md)|[switch](../../../csharp/language-reference/keywords/switch.md)|
-|[this](../../../csharp/language-reference/keywords/this.md)|[throw](../../../csharp/language-reference/keywords/throw.md)|[true](../../../csharp/language-reference/keywords/true.md)|[try](../../../csharp/language-reference/keywords/try-catch.md)|   
-|[typeof](../../../csharp/language-reference/keywords/typeof.md)|[uint](../../../csharp/language-reference/keywords/uint.md)|[ulong](../../../csharp/language-reference/keywords/ulong.md)|[unchecked](../../../csharp/language-reference/keywords/unchecked.md)|
-|[unsafe](../../../csharp/language-reference/keywords/unsafe.md)|[ushort](../../../csharp/language-reference/keywords/ushort.md)|[using](../../../csharp/language-reference/keywords/using.md)|[using static](using-static.md)|
-|[virtual](../../../csharp/language-reference/keywords/virtual.md)|[void](../../../csharp/language-reference/keywords/void.md)|[volatile](../../../csharp/language-reference/keywords/volatile.md)|[while](../../../csharp/language-reference/keywords/while.md)|
+|[in](../../../csharp/language-reference/keywords/in.md)|[int](../../../csharp/language-reference/keywords/int.md)|[interface](../../../csharp/language-reference/keywords/interface.md)|[internal](../../../csharp/language-reference/keywords/internal.md)|
+|[is](../../../csharp/language-reference/keywords/is.md)|[lock](../../../csharp/language-reference/keywords/lock-statement.md)|[long](../../../csharp/language-reference/keywords/long.md)|[namespace](../../../csharp/language-reference/keywords/namespace.md)|
+|[new](../../../csharp/language-reference/keywords/new.md)|[null](../../../csharp/language-reference/keywords/null.md)|[object](../../../csharp/language-reference/keywords/object.md)|[operator](../../../csharp/language-reference/keywords/operator.md)|
+|[out](../../../csharp/language-reference/keywords/out.md)|[override](../../../csharp/language-reference/keywords/override.md)|[params](../../../csharp/language-reference/keywords/params.md)|[private](../../../csharp/language-reference/keywords/private.md)|
+|[protected](../../../csharp/language-reference/keywords/protected.md)|[public](../../../csharp/language-reference/keywords/public.md)|[readonly](../../../csharp/language-reference/keywords/readonly.md)|[ref](../../../csharp/language-reference/keywords/ref.md)|
+|[return](../../../csharp/language-reference/keywords/return.md)|[sbyte](../../../csharp/language-reference/keywords/sbyte.md)|[sealed](../../../csharp/language-reference/keywords/sealed.md)|[short](../../../csharp/language-reference/keywords/short.md)||
+[sizeof](../../../csharp/language-reference/keywords/sizeof.md)|[stackalloc](../../../csharp/language-reference/keywords/stackalloc.md)|[static](../../../csharp/language-reference/keywords/static.md)|[string](../../../csharp/language-reference/keywords/string.md)|
+|[struct](../../../csharp/language-reference/keywords/struct.md)|[switch](../../../csharp/language-reference/keywords/switch.md)|[this](../../../csharp/language-reference/keywords/this.md)|[throw](../../../csharp/language-reference/keywords/throw.md)|
+|[true](../../../csharp/language-reference/keywords/true.md)|[try](../../../csharp/language-reference/keywords/try-catch.md)|[typeof](../../../csharp/language-reference/keywords/typeof.md)|[uint](../../../csharp/language-reference/keywords/uint.md)|
+|[ulong](../../../csharp/language-reference/keywords/ulong.md)|[unchecked](../../../csharp/language-reference/keywords/unchecked.md)|[unsafe](../../../csharp/language-reference/keywords/unsafe.md)|[ushort](../../../csharp/language-reference/keywords/ushort.md)|
+|[using](../../../csharp/language-reference/keywords/using.md)|[using static](using-static.md)|[virtual](../../../csharp/language-reference/keywords/virtual.md)|[void](../../../csharp/language-reference/keywords/void.md)|
+|[volatile](../../../csharp/language-reference/keywords/volatile.md)|[while](../../../csharp/language-reference/keywords/while.md)|
 
 ## Contextual Keywords  
  A contextual keyword is used to provide a specific meaning in the code, but it is not a reserved word in C#. Some contextual keywords, such as `partial` and `where`, have special meanings in two or more contexts.  

docs/csharp/language-reference/keywords/method-parameters.md

@@ -15,15 +15,18 @@ author: "BillWagner"
 ms.author: "wiwagn"
 ---
 # Method Parameters (C# Reference)
-If a parameter is declared for a method without [ref](../../../csharp/language-reference/keywords/ref.md) or [out](../../../csharp/language-reference/keywords/out.md), the parameter can have a value associated with it. That value can be changed in the method, but the changed value will not be retained when control passes back to the calling procedure. By using a method parameter keyword, you can change this behavior.  
+
+Parameters declared for a method without [in](../../../csharp/language-reference/keywords/in-parameter-modifier.md), [ref](../../../csharp/language-reference/keywords/ref.md) or [out](../../../csharp/language-reference/keywords/out-parameter-modifier.md), are passed to the called method by value. That value can be changed in the method, but the changed value will not be retained when control passes back to the calling procedure. By using a method parameter keyword, you can change this behavior.  
 
  This section describes the keywords you can use when declaring method parameters:  
 
 -   [params](../../../csharp/language-reference/keywords/params.md)  
 
+-   [in](../../../csharp/language-reference/keywords/in-parameter-modifier.md)  
+
 -   [ref](../../../csharp/language-reference/keywords/ref.md)  
 
--   [out](../../../csharp/language-reference/keywords/out.md)  
+-   [out](../../../csharp/language-reference/keywords/out-parameter-modifier.md)  
 
 ## See Also  
  [C# Reference](../../../csharp/language-reference/index.md)