Updated getting started page and screenshots. Added IntelliSense engine.md

Documentation/Getting started.md

@@ -1,23 +1,47 @@
 # Getting started
 
-## Configuring IntelliSense
+## Configuring includePath for better IntelliSense results
 
-**Quick summary**: Open your settings file and add `"C_Cpp.intelliSenseEngine": "Default"` to preview the new and improved IntelliSense. Then add the necessary include paths and preprocessor defines to your c_cpp_properties.json file so that IntelliSense can find your symbols.
+This page describes how to configure include paths for folders containing C or C++ files to get better IntelliSense experience. If you're seeing the following message when opening a folder in VS Code, it means the C++ IntelliSense engine needs additional information about the paths in which your symbols are located.
 
-#### The IntelliSense engines
+![Configure includePath for better IntelliSense](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/Configure%20includePath.PNG)
 
-When the extension was first released, we shipped an IntelliSense engine that provided quick, but "fuzzy" results for common operations like auto-complete, parameter help, quick info tooltips, and goto definition. This "tag parser" built up a database of symbols by parsing the most important "tags" from your source files, ignoring preprocessor blocks, local variables, and most errors. More recently, we have begun the process of porting the MSVC IntelliSense engine from Visual Studio to VS Code to provide more accurate results. 
+#### Where to configure the include paths
 
-You can choose the engine that works best for your projects by editing your [user or workspace settings](https://code.visualstudio.com/docs/getstarted/settings). The setting you should modify is `"C_Cpp.intelliSenseEngine"`. There are two values for this setting:
+ When you open a folder, the extension will attempt to locate your system headers based on your operating system, but it does not know about any auxiliary libraries that your project depends on. You can specify the remaining paths by either using the `"C/Cpp: Edit Configurations"` command in the command palette, or by selecting `"Edit "includePath" setting"` in the lightbulb menu (see the screenshot below). The quickiest way to locate the lightbulb is to scroll to the top of the source file and click on any green squiggle, which usually shows up at the first line in the file).
 
-* `"Default"` - use Visual Studio's IntelliSense engine (in preview, the default for VS Code Insiders)
+ ![lightbulb menu "Edit "includePath" setting"](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/Lightbulb.png)
-* `"Tag Parser"` - use the "fuzzy" IntelliSense engine (the default for users on the stable VS Code build)
 
-#### Include paths
+This creates or opens a file called **c_cpp_properties.json** in the .vscode directory in the opened folder in your workspace.  In this file, you can specify the paths to the headers that your project depends on. Look for the section where your current configuration is defined (by default there's one configuration per OS, such as "Win32 or "Mac"), and add your paths in the `"includePath"` setting and defines in the `"defines"` setting. For example, the following screenshot shows a snippet of the file specifying path for the Mac configuration.
 
-In order to get accurate IntelliSense results with either engine, the extension needs some information about your project.  When you open a folder, the extension will attempt to locate your system headers based on your operating system, but it does not know about any auxiliary libraries that your project depends on.  You can specify the remaining paths by using the `"C/Cpp: Edit Configurations"` command in the command palette.
+![c_cpp_properties file snippet](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/c_cpp_properties%20file.PNG)
 
-This command will create or open a file called **c_cpp_properties.json** in your workspace.  In this file, you can specify the paths to the headers that your project depends on.  There are two settings in this file that you should pay particular attention to: `"includePath"` and `"browse.path"`.  `"includePath"` is the setting used by the `"Default"` IntelliSense engine and `"browse.path"` is the setting used by the tag parser engine.  [More information about these settings is documented here](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/FAQ.md#what-is-the-difference-between-includepath-and-browsepath-in-c_cpp_propertiesjson).
+If your build system is able to produce a compile_commands.json file, which can be auto-generated by build systems such as CMake and Ninja, the extension can get the information for the `"includePath"` and `"defines"` from that.  Set the `"compileCommands"` property to the full path to your compile_commands.json file and the extension will use that instead of the `"includes"` and `"defines"` properties for IntelliSense. 
+![use compileCommands setting](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/compile_commands.png)
 
-If your build system is able to produce a compile_commands.json file, the extension can get the information for the `"includePath"` and `"defines"` from that.  Set the `"compileCommands"` property to the full path to your compile_commands.json file and the extension will use that instead of the `"includePath"` and `"defines"` properties for IntelliSense. You should still set the `"browse.path"` property since code navigation uses that property.
+#### Understand which headers can't be located
+
+To figure out which headers you need to specify paths for, you can either hover over the green squiggles to see the message in the tooltip, or open the Problems window to see the errors listed there. The error messsages show which headers the IntelliSense engine is unable to open - it could be the headers that are being included directly or the headers that the included headers are dependent on. The following screenshot shows an example of the error message being shown in the tooltip as well as the Problems window.
+
+![include error message](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/Include%20errors.png)
+
+#### Use the lightbulb suggestions to auto-resolve includePath
+
+You can also leverage the lightbulb path suggestions lightbulb to auto-resolve the included file. When you open a folder, the extension will **recursively** search for potential include paths that match the header files your code is using based on the paths set by the `"browse.path"` setting in **c_cpp_properties.json**. Click on the green squiggles under #include statements and a lightbulb will appear and offer suggestions of paths that will allow IntelliSense to resolve the included file.
+
+![lightbulb suggestions](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/lightbulb%20suggestions.png)
+
+#### Verify the include paths are correctly resolved
+
+There are two ways to verify that the include paths are correctly resolved:
+
+1. The green squiggles in the source file are no longer showing
+2. Error messages are cleared in the Problems window
+
+This indicates that the IntelliSense engine has got the include paths resolved so you can start enjoying the full IntelliSense for your C or C++ code for the current translation unit. Note that you may still see errors on other files if they belong to a different translation unit that requires additional include paths to be configured.
+
+#### See Also
+
+[IntelliSense engines](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/IntelliSense%20engine.md)
+[c_cpp_properties.json](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/c_cpp_properties.json.md)
 

Documentation/LanguageServer/IntelliSense engine.md

@@ -0,0 +1,12 @@
+#### The IntelliSense engines
+
+When the extension was first released, we shipped an IntelliSense engine that provided quick, but "fuzzy" results for common operations like auto-complete, parameter help, quick info tooltips, and goto definition. This "tag parser" built up a database of symbols by parsing the most important "tags" from your source files, ignoring preprocessor blocks, local variables, and most errors. More recently, we have begun the process of porting the MSVC IntelliSense engine from Visual Studio to VS Code to provide more accurate results. 
+
+You can choose the engine that works best for your projects by editing your [user or workspace settings](https://code.visualstudio.com/docs/getstarted/settings). The setting you should modify is `"C_Cpp.intelliSenseEngine"`. There are two values for this setting:
+
+* `"Default"` - use Visual Studio's IntelliSense engine (in preview, the default for VS Code Insiders)
+* `"Tag Parser"` - use the "fuzzy" IntelliSense engine (the default for users on the stable VS Code build)
+
+There are two settings in this file that you should pay particular attention to: `"includePath"` and `"browse.path"`.  `"includePath"` is the setting used by the `"Default"` IntelliSense engine and `"browse.path"` is the setting used by the tag parser engine.  [More information about these settings is documented here](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/FAQ.md#what-is-the-difference-between-includepath-and-browsepath-in-c_cpp_propertiesjson).
+
+#### The fallback