Merge pull request #2551 from LizCasey/v-elicas071818

Content fixes for VS extensibility-debugger articles.

Author: Ja-Dunn

docs/extensibility/debugger/choosing-a-debug-engine-implementation-strategy.md

@@ -14,19 +14,19 @@ manager: douge
 ms.workload: 
   - "vssdk"
 ---
-# Choosing a Debug Engine Implementation Strategy
-Use the run-time architecture to determine your debug engine (DE) implementation strategy. The debug engine may be created in-process to the program to be debugged, in-process to the Visual Studio session debug manager (SDM), or out-of-process to both of them. The following guidelines should help you to choose among these three strategies.  
+# Choose a debug engine implementation strategy
+Use the run-time architecture to determine your debug engine (DE) implementation strategy. You can create the debug engine in-process to the program you're debugging. Create the debug engine in-process to the Visual Studio session debug manager (SDM). Or, create the debug engine out-of-process to both of them. The following guidelines should help you choose among these three strategies.  
 
 ## Guidelines  
- While it is possible for the DE to be out-of-process to both the SDM and the program to be debugged, there is typically no reason to do so. Calls across process boundaries are relatively slow.  
+ While it's possible for the DE to be out-of-process to both the SDM and the program you're debugging, there's typically no reason to do so. Calls across process boundaries are relatively slow.  
 
- Debug engines are already provided for the Win32 native run-time environment and for the common language runtime environment. If you must replace the DE for either of these environments, you must create the DE in-process with the SDM.  
+ Debug engines are already provided for the Win32 native run-time environment and for the common language run-time environment. If you have to replace the DE for either environment, you should create the DE in-process with the SDM.  
 
- Otherwise, you can choose between creating the DE in-process to the SDM or in-process to the program to be debugged. It is important to consider whether the expression evaluator of the DE needs frequent access to the program symbol store, and whether the symbol store can be loaded into memory for rapid access. Also consider the following:  
+ Otherwise, you either create the DE in-process to the SDM or in-process to the program you're debugging. You'll need to consider if the expression evaluator of the DE requires frequent access to the program symbol store. Or, if the symbol store can be loaded into memory for rapid access. Also, consider the following approaches:  
 
 -   If there are not many calls between the expression evaluator and the symbol store, or if the symbol store can be read into the SDM memory space, create the DE in-process to the SDM. You must return the CLSID of the debug engine to the SDM when it attaches to your program. The SDM uses this CLSID to create an in-process instance of the DE.  
 
 -   If the DE must call the program to access the symbol store, create the DE in-process with the program. In this case, the program creates the instance of the DE.  
 
-## See Also  
- [Visual Studio Debugger Extensibility](../../extensibility/debugger/visual-studio-debugger-extensibility.md)
+## See also  
+ [Visual Studio debugger extensibility](../../extensibility/debugger/visual-studio-debugger-extensibility.md)

docs/extensibility/debugger/code-context.md

@@ -14,19 +14,19 @@ manager: douge
 ms.workload: 
   - "vssdk"
 ---
-# Code Context
+# Code context
 In [!INCLUDE[vsprvs](../../code-quality/includes/vsprvs_md.md)] debugging, a **code context**:  
 
 -   Provides an abstraction of a position in code as known to the debug engine (DE). For most run-time architectures today, a code context can be thought of as an address in a program's instruction stream. For nontraditional languages, where code may not be represented by instructions, a code context may be represented by some other means.  
 
--   Describes the current position in the execution stream of the program being debugged.  
+-   Describes the current position in the execution stream of the program you're debugging.  
 
 -   Exists only when a program has stopped at a breakpoint.  
 
 -   Has an associated document context.  
 
 -   Is implemented by an [IDebugCodeContext2](../../extensibility/debugger/reference/idebugcodecontext2.md) interface.  
 
-## See Also  
- [Document Context](../../extensibility/debugger/document-context.md)   
- [Debugger Contexts](../../extensibility/debugger/debugger-contexts.md)
+## See also  
+ [Document context](../../extensibility/debugger/document-context.md)   
+ [Debugger contexts](../../extensibility/debugger/debugger-contexts.md)

docs/extensibility/debugger/common-language-runtime-and-expression-evaluation.md

@@ -15,22 +15,22 @@ manager: douge
 ms.workload: 
   - "vssdk"
 ---
-# Common Language Runtime and Expression Evaluation
+# Common language runtime and expression evaluation
 > [!IMPORTANT]
->  In Visual Studio 2015, this way of implementing expression evaluators is deprecated. For information about implementing CLR expression evaluators, please see [CLR Expression Evaluators](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/CLR-Expression-Evaluators) and [Managed Expression Evaluator Sample](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Managed-Expression-Evaluator-Sample).  
+>  In Visual Studio 2015, this way of implementing expression evaluators is deprecated. For information about implementing CLR expression evaluators, please see [CLR expression evaluators](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/CLR-Expression-Evaluators) and [Managed expression evaluator sample](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Managed-Expression-Evaluator-Sample).  
   
  Compilers, such as Visual Basic and C# (pronounced C-sharp), that target the Common Language Runtime (CLR), produce Microsoft Intermediate Language (MSIL), which is later compiled to native code. The CLR provides a debug engine (DE) to debug the resulting code. If you plan to integrate your proprietary programming language into the Visual Studio IDE, you can choose to compile to MSIL and therefore will not have to write your own DE. However, you will have to write an expression evaluator (EE) that is capable of evaluating expressions within the context of your programming language.  
 
 ## Discussion  
  Computer language expressions are generally parsed to produce a set of data objects and a set of operators used to manipulate them. For example, the expression "A+B" might be parsed to apply the addition operator (+) to the data objects "A" and "B," possibly resulting in another data object. The total set of data objects, operators, and their associations are most often represented in a program as a tree, with the operators at the nodes of the tree and the data objects at the branches. An expression that has been broken down into tree form is often called a parsed tree.  
 
- Once an expression has been parsed, a symbol provider (SP) is called to evaluate each data object. For example, if "A" is defined both in more than one method, then the question "Which A?" must be answered before the value of A can be ascertained. The answer returned by the SP is something like "The third item on the fifth stack frame" or "The A that is 50 bytes beyond the start of the static memory allocated to this method."  
+ Once an expression has been parsed, a symbol provider (SP) is called to evaluate each data object. For example, if "A" is defined both in more than one method, the question "Which A?" must be answered before the value of A can be ascertained. The answer returned by the SP is something like "The third item on the fifth stack frame" or "The A that is 50 bytes beyond the start of the static memory allocated to this method."  
 
- Besides producing MSIL for the program itself, CLR compilers can also produce very descriptive debugging information that is written into a Program DataBase (.pdb) file. As long as a proprietary-language compiler produces debug information in the same format as the CLR compilers, the CLR's SP is able to identify that language's named data objects. Once a named data object has been identified, the EE uses a binder object to associate (or bind) the data object to the memory area that holds the value of that object. The DE can then get or set a new value for the data object.  
+ Besides producing MSIL for the program itself, CLR compilers can also produce very descriptive debugging information that is written into a Program DataBase (*.pdb*) file. As long as a proprietary-language compiler produces debug information in the same format as the CLR compilers, the CLR's SP is able to identify that language's named data objects. Once a named data object has been identified, the EE uses a binder object to associate (or bind) the data object to the memory area that holds the value of that object. The DE can then get or set a new value for the data object.  
 
  A proprietary compiler can provide CLR debugging information by calling the `ISymbolWriter` interface (which is defined in the .NET Framework in the namespace `System.Diagnostics.SymbolStore`). By compiling to MSIL and writing debug information through these interfaces, a proprietary compiler can use the CLR DE and SP. This greatly simplifies integrating a proprietary language into the Visual Studio IDE.  
 
- When the CLR DE calls the proprietary EE to evaluate an expression, the DE supplies the EE with interfaces to an SP and a binder object. Thus, writing a CLR-based debug engine means it is necessary only to implement the appropriate expression evaluator interfaces; the CLR takes care of the binding and the symbol handling for you.  
+ When the CLR DE calls the proprietary EE to evaluate an expression, the DE supplies the EE with interfaces to an SP and a binder object. Thus, writing a CLR-based debug engine means it's necessary only to implement the appropriate expression evaluator interfaces; the CLR takes care of the binding and the symbol handling for you.  
 
-## See Also  
- [Writing a CLR Expression Evaluator](../../extensibility/debugger/writing-a-common-language-runtime-expression-evaluator.md)
+## See also  
+ [Write a CLR expression evaluator](../../extensibility/debugger/writing-a-common-language-runtime-expression-evaluator.md)

docs/extensibility/debugger/contingentproperties-class-internal-members.md

@@ -15,7 +15,7 @@ manager: douge
 ms.workload: 
   - "vssdk"
 ---
-# ContingentProperties Class - Internal Members
+# ContingentProperties class - internal members
 Contains additional properties for a <xref:System.Threading.Tasks.Task> object.  
 
  **Namespace:** <xref:System.Threading.Tasks?displayProperty=fullName>  
@@ -26,7 +26,7 @@ Contains additional properties for a <xref:System.Threading.Tasks.Task> object.
 
 ## Syntax  
 
-```  
+```csharp  
 .class auto ansi nested assembly beforefieldinit ContingentProperties  
        extends System.Object  
 ```  
@@ -42,5 +42,5 @@ Contains additional properties for a <xref:System.Threading.Tasks.Task> object.
 ## Remarks  
  The .NET Framework initializes the fields of this class only when they are needed.  
 
-## See Also  
- [Parallel Extension Internals for the .NET Framework](../../extensibility/debugger/parallel-extension-internals-for-the-dotnet-framework.md)
+## See also  
+ [Parallel extension internals for the .NET Framework](../../extensibility/debugger/parallel-extension-internals-for-the-dotnet-framework.md)

docs/extensibility/debugger/control-events.md

@@ -14,10 +14,10 @@ manager: douge
 ms.workload: 
   - "vssdk"
 ---
-# Control Events
+# Control events
 You must send events during the controlled execution of your program. All of the events are sent using the [IDebugEvent2](../../extensibility/debugger/reference/idebugevent2.md) interface and have attributes that require you to implement the [IDebugEvent2::GetAttributes](../../extensibility/debugger/reference/idebugevent2-getattributes.md) method.  
 
-## Additional Methods  
+## Additional methods  
  Some events require implementation of additional methods, as follows:  
 
 -   Sending the [IDebugEngineCreateEvent2](../../extensibility/debugger/reference/idebugenginecreateevent2.md) interface when the debug engine (DE) is initialized requires you to implement the [IDebugEngineCreateEvent2::GetEngine](../../extensibility/debugger/reference/idebugenginecreateevent2-getengine.md) method.  
@@ -34,5 +34,5 @@ You must send events during the controlled execution of your program. All of the
 
  For your engine to write string-style output, you must implement the [IDebugOutputStringEvent2::GetString](../../extensibility/debugger/reference/idebugoutputstringevent2-getstring.md) method.  
 
-## See Also  
- [Execution Control and State Evaluation](../../extensibility/debugger/execution-control-and-state-evaluation.md)
+## See also  
+ [Execution control and state evaluation](../../extensibility/debugger/execution-control-and-state-evaluation.md)

docs/extensibility/debugger/control-of-execution.md

@@ -14,27 +14,27 @@ manager: douge
 ms.workload: 
   - "vssdk"
 ---
-# Control of Execution
+# Control of execution
 The debug engine (DE) typically sends one of the following events as the last startup event:  
 
 -   The entry point event, if attaching to a newly launched program  
 
 -   The load complete event, if attaching to a program that is already running  
 
- Both these events are stopping events, meaning that the DE waits for a response from the user by means of the IDE. For more information, see [Operational Modes](../../extensibility/debugger/operational-modes.md).  
+ Both these events are stopping events, meaning that the DE waits for a response from the user by means of the IDE. For more information, see [Operational modes](../../extensibility/debugger/operational-modes.md).  
 
-## Stopping Event  
+## Stopping event  
  When a stopping event is sent to the debug session:  
 
 1.  The program and thread that contain the current instruction pointer can be obtained from the event interface.  
 
-2.  The IDE determines the current source code file and position, which it displays highlighted in the editor.  
+2.  The IDE determines the current source code file and position, which it displays as highlighted in the editor.  
 
 3.  The debug session typically responds to this first stopping event by calling the program's **Continue** method.  
 
-4.  The program then runs until it encounters a stopping condition, such as hitting a breakpoint, in which case the DE sends a breakpoint event to the debug session. The breakpoint event is a stopping event, and the DE again waits for a user response.  
+4.  The program then runs until it encounters a stopping condition, such as hitting a breakpoint. In which case, the DE sends a breakpoint event to the debug session. The breakpoint event is a stopping event, and the DE again waits for a user response.  
 
-5.  If the user elects to step into, over, or out of a function, the IDE prompts the debug session to call the program's `Step` method, passing it the unit of step (instruction, statement, or line) and the kind of step—that is, whether to step into, over, or out of the function. When the step is complete, the DE sends a step complete event to the debug session, which is a stopping event.  
+5.  If the user elects to step into, over, or out of a function, the IDE prompts the debug session to call the program's `Step` method. The IDE then passes the unit of step (instruction, statement, or line) and the type of step (whether to step into, over, or out of the function). When the step is complete, the DE sends a step complete event to the debug session, which is a stopping event.  
 
      -or-  
 
@@ -48,13 +48,13 @@ The debug engine (DE) typically sends one of the following events as the last st
 
  The SDM typically responds to this first stopping event by calling [IDebugProgram2::Continue](../../extensibility/debugger/reference/idebugprogram2-continue.md). The program then runs until it encounters a stopping condition, such as hitting a breakpoint, in which case the DE sends an [IDebugBreakpointEvent2 Interface](../../extensibility/debugger/reference/idebugbreakpointevent2.md) to the SDM. The breakpoint event is a stopping event, and the DE again waits for a user response.  
 
- If the user elects to step into, over, or out of a function, the IDE prompts the SDM to call [IDebugProgram2::Step](../../extensibility/debugger/reference/idebugprogram2-step.md), passing it the [STEPUNIT](../../extensibility/debugger/reference/stepunit.md) (instruction, statement, or line) and the [STEPKIND](../../extensibility/debugger/reference/stepkind.md), that is, whether to step into, over, or out of the function. When the step is complete, the DE sends an [IDebugStepCompleteEvent2](../../extensibility/debugger/reference/idebugstepcompleteevent2.md) interface to the SDM, which is a stopping event.  
+ If the user elects to step into, over, or out of a function, the IDE prompts the SDM to call [IDebugProgram2::Step](../../extensibility/debugger/reference/idebugprogram2-step.md). The IDE then passes the [STEPUNIT](../../extensibility/debugger/reference/stepunit.md) (instruction, statement, or line) and the [STEPKIND](../../extensibility/debugger/reference/stepkind.md), that is, whether to step into, over, or out of the function. When the step is complete, the DE sends an [IDebugStepCompleteEvent2](../../extensibility/debugger/reference/idebugstepcompleteevent2.md) interface to the SDM, which is a stopping event.  
 
  If the user elects to continue executing from the current instruction pointer, the IDE asks the SDM to call [IDebugProgram2::Execute](../../extensibility/debugger/reference/idebugprogram2-execute.md). The program resumes execution until it encounters the next stopping condition.  
 
- If the debug package is to ignore a particular stopping event, the debug package calls the SDM, which calls [IDebugProgram2::Continue](../../extensibility/debugger/reference/idebugprogram2-continue.md). If the program was stepping into, over, or out of a function when it encountered the stopping condition, then it continues the step. This implies that the program maintains a stepping state, so that it knows how to continue.  
+ If the debug package is to ignore a particular stopping event, the debug package calls the SDM, which calls [IDebugProgram2::Continue](../../extensibility/debugger/reference/idebugprogram2-continue.md). If the program was stepping into, over, or out of a function when it encountered the stopping condition, it continues the step. This implies that the program maintains a stepping state, so that it knows how to continue.  
 
  The calls the SDM makes to `Step`, **Execute**, and **Continue** are asynchronous, which means that the SDM expects the call to return quickly. If the DE sends the SDM a stopping event on the same thread before `Step`, **Execute**, or **Continue** returns, the SDM hangs.  
 
-## See Also  
- [Debugging Tasks](../../extensibility/debugger/debugging-tasks.md)
+## See also  
+ [Debug tasks](../../extensibility/debugger/debugging-tasks.md)