updated getting started and added intellisense engine page

Author: ronglums

Documentation/Getting started.md

@@ -22,7 +22,7 @@ You can specify the remaining paths using one of the techniques described below.
 
 #### 1. Use compile_commands.json file to supply includePaths and defines information
 
-The extension can get the information for `"includePath"` and `"defines"` from a compile_commands.json file, which can be auto-generated by many build systems such as CMake and Ninja.  Set the `"compileCommands"` property in **c_cpp_properties.json** 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.
+The extension can get the information for `"includePath"` and `"defines"` from a compile_commands.json file, which can be auto-generated by many build systems such as CMake and Ninja. Look for the section where your current configuration is defined (by default there's one configuration per OS, such as "Win32 or "Mac"), and set the `"compileCommands"` property in **c_cpp_properties.json** 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/ronglu-edit/Images/compile_commands.png)
 

Documentation/LanguageServer/IntelliSense engine.md

@@ -1,12 +1,35 @@
-#### The IntelliSense engines
+#### 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. 
+There are two IntelliSense engines used to power the C/C++ IntelliSense experience in VS Code. 
 
-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"` - Visual Studio's IntelliSense engine, which is the default engine that provides semantic-aware IntelliSense features
+* `"Tag Parser"` - the "fuzzy" IntelliSense engine that provides quick but "fuzzy" results, is used to provide the fallback experience if the default engine is unable to fully resolve include paths
 
-* `"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)
+Ultimately all the IntelliSense and code browsing features will be powered by the "Default" engine. The following features have been implemented so far:
 
-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).
+* Auto-complete suggestions for class/struct/namespace members
+* Parameter hints
+* Quick info (hover over tooltip)
+* Error squiggles
+* Reference highlighting
 
-#### The fallback 
+The other IntelliSense features, such as global auto-complete, and code browsing features, such as Go to definition/declaration, are currently powered by the "Tag Parser" based engine.
+
+#### includePath and browse.path
+The two IntelliSense engines use two differnt settings in the **c_cpp_properties.json** file for specifying include paths. This file is located in the .vscode directory in the opened folder. You can create or open this file by either using the "C/Cpp: Edit Configurations" command in the command palette or by selecting "Edit "includePath" setting" in the lightbulb menu. Look for the following settings in the section where your current configuration is defined (by default there's one configuration per OS, such as "Win32 or "Mac").
+
+* `"includePath"`: This array of path strings is used by the "Default" IntelliSense engine. The paths that you specify for this setting are the same paths that you would send to your compiler via the -I switch. When your source files are parsed, the IntelliSense engine will prepend these paths to the files specified by your #include directives while attempting to resolve them. These paths are searched **non-recursively**.
+
+* `"browse.path"`: This array of path strings is used by the "Tag Parser" (a.k.a. "browse engine"). This engine will **recursively** enumerate all files under the paths specified and track them as potential includes while tag parsing your project folder. To disable recursive enumeration of a path, you can append a /* to the path string.
+
+#### How fallback works and how to control the behavior
+
+The extension first tries to fully parse any opened file using the "Default" IntelliSense engine. If it discovers that it cannot find a header file or a dependency, it will fall back to the tag parser and provide the fuzzy IntelliSense behavior. The fallback affects a full translation unit (TU), not just a single open file. The Problems panel provides details about unresolved headers and dependencies. Other opened TUs will continue to use the "Default" IntelliSense engine provided that all #include dependencies are resolved. 
+
+We recognize that resolving all #include’s may not be necessary for all projects and you may still want to experience the productivity benefits of using the "Default" sematic engine without customizing the default include path. For that, the “Force semantic IntelliSense” action can be chosen. When invoked, all unresolved #include squiggles will turn red and semantic member list and linting will be enabled in all files regardless of whether or not #include statements can be resolved.
+
+#### IntelliSense engine setting
+We recommend to use the "Default" engine for the best IntelliSense experience. However, it is possible to explicitly choose the IntelliSense 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 
+* `"Tag Parser"` - use the "fuzzy" IntelliSense engine