More documentation updates (#202)

* Add some content to the design page.

* More design doc updates

* Update user guide docs

docs/design/index.md

@@ -1,11 +1,64 @@
 # Design and Implementation
 
-Design and implementation notes.
+The SQL Tools Service is designed as a stand-alone collection of database management operations.  The service can be integrated into a 
+variety SQL data developer and DBA host applications.  For example, the below image illustrates the high-level MSSQL for VS Code 
+composition.  The extension's UI components run in the VS Code process.  This code is written in TypeScipt and communicates with 
+the service process over a JSON-RPC stdio channel.
 
-![Host Process](../images/hostprocess.png)
+The service process consists of SMO SDK for .Net Core and higher-level SQL management components.  The service provides features such as
+common language service operations (IntelliSense auto-complete suggestions, peek definition, SQL error diagnostics, quickinfo hovers), connection management,
+and query execution.
 
-![Connected Binding](../images/connected_bind.png)
+<img src='../images/hostprocess.png' width='800px' />
 
-![Message Dispatch](../images/msgdispatch.png)
+The SQL Tools Service is built on top of the SMO SDK for .Net Core and System.Data components built into .Net Core.  This allows the service
+to provide rich SQL Server support that runs on Windows, Mac OS, and Linux operating systems.  The service can work with on-prem SQL Server,
+SQL DB, and Azure SQL DW instances.
+
+## Language Service
+The SQL Tools Service implements the [language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md) 
+implemented by VS Code.  This includes support for the following operations.
+
+* Autocomplete suggestions
+* Peek\Go to definition
+* SQL error checking diagnostics
+* QuickInfo hover tooltips
+* Function signature info
+
+The language service is primarily implemented in @Microsoft.SqlTools.ServiceLayer.LanguageServices
+ ([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/LanguageServices/LanguageService.cs)).
+The language service depends heavily on the Microsoft.SqlServer.SqlParser assembly.
+
+The language service component shares database connections across editor windows.  Operations are routed
+through a queue to control concurrency when accessing shared database connection and metadata resources.  
+The binding queue is implemented in @Microsoft.SqlTools.ServiceLayer.LanguageServices.ConnectedBindingQueue
+ ([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/LanguageServices/ConnectedBindingQueue.cs) and 
+  [src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/LanguageServices/BindingQueue.cs)).
+  
+<img src='../images/connected_bind.png' width='800px' />
+
+## Message Dispatcher
+
+The JSON-RPC mechanism is build on a message dispatcher.  Messages are read from stdio and serialized\deserialized
+using JSON.Net.  Message handlers are registered with the dispatcher.  Ass the messages are processed by
+the dispatcher queue they are routed to any registered handlers.  The dispatch queue processes messages 
+serially.
+
+<img src='../images/msgdispatch.png' width='650px' />
+
+The below sequence diagram show an example of how the language service may process a error checking diagnostics
+workflow.  In this example the editor hosts a language service client that responds to user initiated editing events.
+The user actions are translated into a sequence of request\response pairs and one-way event notifications. 
+Messages can be initiated from either the server or the client.
+
+<img src='../images/msgdispatchexample.png' width='800px' />
+
+## Query Execution
+The Query Execution component provides the ability to execute SQL scripts against SQL Server instances.
+This functionality builds onto the support in System.Data to provide features batch processing support 
+and a file-backed cache for large resultsets.
+
+@Microsoft.SqlTools.ServiceLayer.QueryExecution.QueryExecutionService
+([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/QueryExecution/QueryExecutionService.cs)) 
+is the class that implements the query execution protocol.
 
-![Message Dispatch Example](../images/msgdispatchexample.png)

docs/guide/introduction.md

@@ -4,8 +4,13 @@
 > important information.  If you feel that a particular area is missing or
 > poorly explained, please feel free to file an issue at our [GitHub site](https://github.com/Microsoft/sqltoolsservice/issues)
 
-SQL Tools Service is a tool that provides useful services to code
+SQL Tools Service is a API that provides useful services to database developer 
-editors that need a great SQL Server editing experience.
+and management tools.
+
+## The JSON-RPC API
+The SQL Tools Service exposes its feature set as a JSON-RPC over stdio.  See 
+the API details at [JSON-RPC Protocol](jsonrpc_protocol.md) and checkout some
+usage examples at [Using the JSON-RPC API](using_the_jsonrpc_api.md).
 
 ## The .NET API
 
@@ -13,5 +18,4 @@ The .NET API provides the complete set of services which can be used in
 code editors or any other type of application.
 
 If you're a developer that would like to use SQL Tools Service in
-a .NET application, read the page titled [Using the .NET API](using_the_dotnet_api.md)
+a .NET application, checkout the [.Net API reference](../api/index.md).
-to learn more.

docs/guide/jsonrpc_protocol.md

@@ -1,4 +1,4 @@
-# Using the JSON-RPC API
+# JSON-RPC Protocol
 
 The JSON-RPC API provides an host-agnostic interface for
 leveraging the core .NET API.
@@ -19,28 +19,31 @@ which contains all of the user's SQL script files for a given project.
 
 ## Messages overview
 
+The SQL Tools Service implements portions of the 
+[language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md)
+defined by VS Code.  Some portions of this protocol reference have been duplicated here for 
+convenience.  
+
+It additionally implements several other API to provide database management
+services such as connection management or query execution.
+
+This document provides the protocol specification for all the service's JSON-RPC APIs.
+
 General
 
 * :leftwards_arrow_with_hook: [initialize](#initialize) 
 * :leftwards_arrow_with_hook: [shutdown](#shutdown) 
 * :arrow_right: [exit](#exit) 
 * :arrow_right: [$/cancelRequest](#cancelRequest)
+* :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration) 
+* :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles) 
 
-Window
+Language Service
 
 * :arrow_left: [window/showMessage](#window_showMessage) 
 * :arrow_right_hook: [window/showMessageRequest](#window_showMessageRequest) 
 * :arrow_left: [window/logMessage](#window_logMessage) 
 * :arrow_left: [telemetry/event](#telemetry_event) 
-
-Workspace
-
-* :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration) 
-* :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles) 
-* :leftwards_arrow_with_hook: [workspace/symbol](#workspace_symbol) 
-
-Document
-
 * :arrow_left: [textDocument/publishDiagnostics](#textDocument_publishDiagnostics) 
 * :arrow_right: [textDocument/didChange](#textDocument_didChange)  
 * :arrow_right: [textDocument/didClose](#textDocument_didClose) 
@@ -51,18 +54,12 @@ Document
 * :leftwards_arrow_with_hook: [textDocument/hover](#textDocument_hover) 
 * :leftwards_arrow_with_hook: [textDocument/signatureHelp](#textDocument_signatureHelp) 
 * :leftwards_arrow_with_hook: [textDocument/references](#textDocument_references) 
-* :leftwards_arrow_with_hook: [textDocument/documentHighlight](#textDocument_documentHighlight) 
-* :leftwards_arrow_with_hook: [textDocument/documentSymbol](#textDocument_documentSymbol) 
-* :leftwards_arrow_with_hook: [textDocument/formatting](#textDocument_formatting) 
-* :leftwards_arrow_with_hook: [textDocument/rangeFormatting](#textDocument_rangeFormatting) 
-* :leftwards_arrow_with_hook: [textDocument/onTypeFormatting](#textDocument_onTypeFormatting) 
 * :leftwards_arrow_with_hook: [textDocument/definition](#textDocument_definition) 
-* :leftwards_arrow_with_hook: [textDocument/codeAction](#textDocument_codeAction) 
+
-* :leftwards_arrow_with_hook: [textDocument/codeLens](#textDocument_codeLens) 
+Connection Management
-* :leftwards_arrow_with_hook: [codeLens/resolve](#codeLens_resolve) 
+
-* :leftwards_arrow_with_hook: [textDocument/documentLink](#textDocument_documentLink) 
+Query Execution
-* :leftwards_arrow_with_hook: [documentLink/resolve](#documentLink_resolve) 
+
-* :leftwards_arrow_with_hook: [textDocument/rename](#textDocument_rename) 
 
 # Message Protocol
 

docs/guide/toc.md

@@ -1,3 +1,3 @@
 # [Introduction](introduction.md)
-# [Using the JSON-RPC API](using_the_host_process.md)
+# [JSON-RPC Protocol](jsonrpc_protocol.md)
-# [Using the .NET API](using_the_dotnet_api.md)
+# [Using the JSON-RPC API](using_the_jsonrpc_api.md)

docs/guide/using_the_jsonrpc_api.md

@@ -1,4 +1,4 @@
-# Using the SQL Tools Service .NET API
+# Using the JSON-RPC API
 
 > NOTE: The [API Reference](../api/index.md) is the best starting point for working directly with
 > the .NET API.