Merge pull request #4993 from MicrosoftDocs/master

7/12/2019 AM Publish

Author: Taojunshen

docs/code-quality/annotating-function-parameters-and-return-values.md

@@ -1,6 +1,6 @@
 ---
 title: Annotating Function Parameters and Return Values
-ms.date: 11/04/2016
+ms.date: 07/11/2019
 ms.topic: "conceptual"
 f1_keywords:
   - "_Outptr_opt_result_bytebuffer_to_"
@@ -119,6 +119,9 @@ f1_keywords:
   - "_Outref_result_bytebuffer_"
   - "_Result_nullonfailure_"
   - "_Ret_null_"
+  - "_Scanf_format_string_"
+  - "_Scanf_s_format_string_"
+  - "_Printf_format_string_"
 ms.assetid: 82826a3d-0c81-421c-8ffe-4072555dca3a
 author: mikeblome
 ms.author: mblome
@@ -279,6 +282,7 @@ This article describes typical uses of annotations for simple function parameter
      A pointer to a null-terminated array for which the expression `p` - `_Curr_` (that is, `p` minus `_Curr_`) is defined by the appropriate language standard.  The elements prior to `p` do not have to be valid in pre-state and must be valid in post-state.
 
 ## Optional Pointer Parameters
+
  When a pointer parameter annotation includes `_opt_`, it indicates that the parameter may be null. Otherwise, the annotation performs the same as the version that doesn't include `_opt_`. Here is a list of the `_opt_` variants of the pointer parameter annotations:
 
 ||||
@@ -378,6 +382,7 @@ This article describes typical uses of annotations for simple function parameter
    The returned pointer points to a valid buffer if the function succeeds, or null if the function fails. This annotation is for a reference parameter.
 
 ## Output Reference Parameters
+
  A common use of the reference parameter is for output parameters.  For simple output reference parameters—for example, `int&`—`_Out_` provides the correct semantics.  However, when the output value is a pointer—for example `int *&`—the equivalent pointer annotations like `_Outptr_ int **` don't provide the correct semantics.  To concisely express the semantics of output reference parameters for pointer types, use these composite annotations:
 
  **Annotations and Descriptions**
@@ -439,13 +444,65 @@ This article describes typical uses of annotations for simple function parameter
      Result must be valid in post-state, but may be null in post state. Points to valid buffer of `s` bytes of valid elements.
 
 ## Return Values
+
  The return value of a function resembles an `_Out_` parameter but is at a different level of de-reference, and you don't have to consider the concept of the pointer to the result.  For the following annotations, the return value is the annotated object—a scalar, a pointer to a struct, or a pointer to a buffer. These annotations have the same semantics as the corresponding `_Out_` annotation.
 
 |||
 |-|-|
 |`_Ret_z_`<br /><br /> `_Ret_writes_(s)`<br /><br /> `_Ret_writes_bytes_(s)`<br /><br /> `_Ret_writes_z_(s)`<br /><br /> `_Ret_writes_to_(s,c)`<br /><br /> `_Ret_writes_maybenull_(s)`<br /><br /> `_Ret_writes_to_maybenull_(s)`<br /><br /> `_Ret_writes_maybenull_z_(s)`|`_Ret_maybenull_`<br /><br /> `_Ret_maybenull_z_`<br /><br /> `_Ret_null_`<br /><br /> `_Ret_notnull_`<br /><br /> `_Ret_writes_bytes_to_`<br /><br /> `_Ret_writes_bytes_maybenull_`<br /><br /> `_Ret_writes_bytes_to_maybenull_`|
 
+## Format string parameters
+
+- `_Printf_format_string_`
+     Indicates that the parameter is a format string for use in a `printf` expression.
+
+     **Example**
+
+    ```cpp
+    int MyPrintF(_Printf_format_string_ const wchar_t* format, ...)
+    {
+           va_list args;
+           va_start(args, format);
+           int ret = vwprintf(format, args);
+           va_end(args);
+           return ret;
+    }
+    ```
+
+- `_Scanf_format_string_`
+     Indicates that the parameter is a format string for use in a `scanf` expression.
+
+     **Example**
+
+    ```cpp
+    int MyScanF(_Scanf_format_string_ const wchar_t* format, ...)
+    {
+           va_list args;
+           va_start(args, format);
+           int ret = vwscanf(format, args);
+           va_end(args);
+           return ret;
+    }
+    ```
+
+- `_Scanf_s_format_string_`
+     Indicates that the parameter is a format string for use in a `scanf_s` expression.
+
+     **Example**
+
+    ```cpp
+    int MyScanF_s(_Scanf_s_format_string_ const wchar_t* format, ...)
+    {
+           va_list args; 
+           va_start(args, format);
+           int ret = vwscanf_s(format, args);
+           va_end(args); 
+           return ret;
+    }
+    ```
+
 ## Other Common Annotations
+
  **Annotations and Descriptions**
 
 - `_In_range_(low, hi)`
@@ -484,6 +541,7 @@ This article describes typical uses of annotations for simple function parameter
      `min(pM->nSize, sizeof(MyStruct))`
 
 ## Related Resources
+
  [Code Analysis Team Blog](http://go.microsoft.com/fwlink/?LinkId=251197)
 
 ## See Also

docs/code-quality/fxcop-analyzers.yml

@@ -1,10 +1,10 @@
 ### YamlMime:YamlDocument
 documentType: LandingData
-title: Migrate from FxCop code analysis to .NET compiler platform analyzers
+title: Migrate from binary analysis (FxCop) to source analysis (FxCop analyzers)
 metadata:
   title: FxCop migration documentation
-  description: Learn how to migrate from legacy FxCop to analyzers for code analysis.
-  ms.date: 07/18/2018
+  description: Learn how to move from legacy binary analysis (FxCop) to source analysis (FxCop analyzers) when you analyze code.
+  ms.date: 07/11/2019
   ms.prod: visual-studio-dev16
   ms.technology: vs-ide-code-analysis
   ms.topic: landing-page
@@ -14,7 +14,7 @@ metadata:
   author: gewarren
   manager: jillfra
 abstract:
-  description: Learn how to analyze code for the first time, or how to migrate from FxCop to the new way of analyzing managed code using analyzers.
+  description: Learn how to analyze code for the first time or how to migrate from binary analysis (FxCop) to the new way of analyzing managed code using source analysis (FxCop analyzers).
   aside:
     image:
       alt: Common management tasks logo
@@ -25,7 +25,7 @@ abstract:
 sections:
 - title: Frequently asked questions
   items:
-  - html: Get answers to some <a href="fxcop-analyzers-faq.md">frequently asked questions</a> about the differences between FxCop and analyzers.
+  - html: Get answers to some <a href="fxcop-analyzers-faq.md">frequently asked questions</a> about the differences between binary FxCop analysis and source analysis using FxCop analyzers.
 
 - title: If you're new to code analysis...
   items:
@@ -55,15 +55,15 @@ sections:
           src: https://docs.microsoft.com/media/common/i_cligeneric.svg
         title: Command-line usage
 
-- title: If you're an FxCop user...
+- title: If you're currently using binary analysis (FxCop)...
   items:
   - type: list
     style: cards
     className: cardsM
     columns: 2
     items:
       - href: roslyn-analyzers-overview.md#roslyn-analyzers-vs-static-code-analysis
-        html: <p>Learn the differences between static (FxCop) and analyzer code analysis.</p>
+        html: <p>Learn the differences between binary analysis (FxCop) and source analysis (FxCop analyzers).</p>
         image:
           src: https://docs.microsoft.com/media/common/i_learn-about.svg
         title: What's different?
@@ -73,7 +73,7 @@ sections:
           src: https://docs.microsoft.com/media/common/i_setup.svg
         title: Install FxCop analyzers
       - href: fxcop-rule-port-status.md
-        html: <p>Lists the static code analysis FxCop rules that have been ported to FxCop analyzers.</p>
+        html: <p>Lists the binary analysis (FxCop) rules that have been ported to source analysis (FxCop analyzers).</p>
         image:
           src: https://docs.microsoft.com/media/common/i_upgrade.svg
         title: Ported and unported rules

docs/debugger/debugging-errors-and-warning-dialog-boxes.md

@@ -31,6 +31,8 @@ Below are the errors and warning dialog boxes you may encounter while debugging
  [Cannot Change Value Dialog Box](../debugger/cannot-change-value-dialog-box.md)
 
  [Debugger Cannot Display Source Code or Disassembly](../debugger/debugger-cannot-display-source-code-or-disassembly.md)
+ 
+ [Debugger Services Running Out of Memory](../debugger/error-debugger-services-no-memory.md)
 
  [Executable for Debugging Session Dialog Box](../debugger/executable-for-debugging-session-dialog-box.md)
 

docs/debugger/error-debugger-services-no-memory.md

@@ -0,0 +1,30 @@
+---
+title: "Debugger Services Running Out of Memory | Microsoft Docs"
+ms.date: "07/10/2019"
+ms.topic: "troubleshooting"
+f1_keywords:
+  - "vs.debug.error.debug_no_memory"
+dev_langs:
+  - "CSharp"
+  - "VB"
+  - "FSharp"
+  - "C++"
+helpviewer_keywords:
+  - "debugger"
+author: "isadorasophia"
+ms.author: "isgarcia"
+manager: caslan
+ms.workload:
+  - "multiple"
+---
+# Debugger Services Running Out of Memory
+The Debugging Services ran out of memory and caused the termination of the debugging session.
+
+## To investigate this error on Windows
+- You can check the process memory graph in the **Diagnostics Tools** window to see if the target application is experiencing huge growth in memory. If so, use the **Memory Usage** tool to diagnose what is the underlying issue, see [Analyze memory usage](../profiling/memory-usage.md).
+
+- If the target application does not seem to be consuming a lot of memory, use the **Task Manager** window to check out memory usage of Visual Studio (devenv.exe), the worker process (msvsmon.exe), or of VS Code (vsdbg.exe/vsdbg-ui.exe) to determine if this is a debugger problem. If the process running out of memory is devenv.exe, consider reducing the number of Visual Studio extensions running.
+
+## See Also
+- [Blog post: Analyze CPU and Memory while Debugging](https://devblogs.microsoft.com/visualstudio/analyze-cpu-memory-while-debugging/)
+- [About Memory Management](/windows/win32/memory/about-memory-management)

docs/debugger/toc.yml

@@ -710,6 +710,8 @@
         href: cannot-change-value-dialog-box.md
       - name: Debugger Cannot Display Source Code or Disassembly
         href: debugger-cannot-display-source-code-or-disassembly.md
+      - name: Debugger Services Running Out of Memory
+        href: error-debugger-services-no-memory.md
       - name: Executable for Debugging Session dialog box
         href: executable-for-debugging-session-dialog-box.md
       - name: Edit and Continue dialog box (C++)

docs/extensibility/set-install-root.md

@@ -9,19 +9,20 @@ manager: jillfra
 ms.workload:
   - "vssdk"
 ---
-# Installing outside the extensions folder
+# Install outside the extensions folder
 
-Starting with Visual Studio 2017 and VSIX v3 (version 3), there is now support for installing extension assets outside of the extensions folder. Currently, the following locations are enabled as valid installation locations (where [INSTALLDIR] is mapped to the Visual Studio instance's installation directory):
+Starting with Visual Studio 2017 and VSIX v3 (version 3), extension assets can be installed outside of the extensions folder. Currently, the following locations are enabled as valid installation locations (where [INSTALLDIR] is mapped to the Visual Studio instance's installation directory):
 
 * [INSTALLDIR]\MSBuild
 * [INSTALLDIR]\Xml\Schemas
 * [INSTALLDIR]\Common7\IDE\PublicAssemblies
 * [INSTALLDIR]\Licenses
 * [INSTALLDIR]\Common7\IDE\ReferenceAssemblies
 * [INSTALLDIR]\Common7\IDE\RemoteDebugger
-* [INSTALLDIR]\Common7\IDE\VC\VCTargets
+* [INSTALLDIR]\Common7\IDE\VC\VCTargets (only supported for Visual Studio 2017; deprecated for Visual Studio 2019 and later)
 
->**Note:** The VSIX format does not allow you to install outside the VS install folder structure.
+> [!NOTE]
+> The VSIX format doesn't allow you to install outside the Visual Studio install folder structure. 
 
 In order to support installing to these directories, the VSIX must be installed "per-instance per-machine". This can be enabled by checking the "all-users" checkbox in the extension.vsixmanifest designer:
 
@@ -43,7 +44,8 @@ This will add some metadata to the corresponding `ProjectReference` property ins
  </ProjectReference>
 ```
 
->**Note:** You can edit the .csproj file directly, if you prefer.
+> [!NOTE]
+> You can edit the .csproj file directly, if you prefer.
 
 ## How to set a subpath under the InstallRoot
 

docs/msbuild/how-to-use-project-sdk.md

@@ -50,7 +50,15 @@ During evaluation of the project, [!INCLUDE[vstecmsbuild](../extensibility/inter
     </Project>
     ```
 
-    An implicit import is added to the top and bottom of the project as discussed above.  The format of the `Sdk` attribute is `Name[/Version]` where Version is optional.  For example, you can specify `My.Custom.Sdk/1.2.3`.
+    An implicit import is added to the top and bottom of the project as discussed above.
+    
+    To specify a specific version of the SDK you may append it to the `Sdk` attribute:
+
+    ```xml
+    <Project Sdk="My.Custom.Sdk/1.2.3">
+        ...
+    </Project>
+    ```
 
     > [!NOTE]
     > This is currently the only supported way to reference a project SDK in Visual Studio for Mac.

docs/msbuild/msbuild-transforms.md

@@ -87,16 +87,16 @@ For example, if the items in the @(RESXFile) item list are *Form1.resx*, *Form2.
 
 ```
 rootdir: C:\
-fullpath: C:\xmake\sub1\sub2\sub3\myfile.xsd
-rootdir + directory + filename + extension: C:\xmake\sub1\sub2\sub3\myfile.xsd
+fullpath: C:\sub0\sub1\sub2\sub3\myfile.xsd
+rootdir + directory + filename + extension: C:\sub0\sub1\sub2\sub3\myfile.xsd
 identity: sub1\sub2\sub3\myfile.xsd
 filename: myfile
-directory: xmake\sub1\sub2\sub3\
+directory: sub0\sub1\sub2\sub3\
 relativedir: sub1\sub2\sub3\
 extension: .xsd
 ```
 
 ## See also
 - [MSBuild concepts](../msbuild/msbuild-concepts.md)
 - [MSBuild reference](../msbuild/msbuild-reference.md)
-- [How to: Build incrementally](../msbuild/how-to-build-incrementally.md)
+- [How to: Build incrementally](../msbuild/how-to-build-incrementally.md)