More documentation.

EXAMPLES.md

@@ -0,0 +1,76 @@
+# Code Examples
+
+This document provides simple examples of how to use the Solargraph library. The examples are intended as a starting point for developers who want to modify or extend the library, or integrate its tools into other software.
+
+Language client implementors who want to connect to Solargraph language servers should refer to [LANGUAGE_SERVER.md](LANGUAGE_SERVER.md).
+
+## Querying Ruby Core Methods
+
+```Ruby
+api_map = Solargraph::ApiMap.new
+pins = api_map.get_methods('String') # Get public instance methods of the String class
+```
+
+## Adding a File to an ApiMap
+
+```Ruby
+api_map = Solargraph::ApiMap.new
+source = Solargraph::Source.load_string('class MyClass; end', 'my_class.rb')
+api_map.virtualize source # Add the source to the map
+pins = api_map.get_constants('') # The constants in the global namespace will include `MyClass`
+```
+
+## Adding a Workspace to an ApiMap
+
+```Ruby
+workspace = Solargraph::Workspace.new('/path/to/project')
+api_map = Solargraph::ApiMap.new(workspace)
+pins = api_map.get_constants('') # Results will include constants defined in the project's code
+```
+
+## Querying Definitions from a Location in Source Code
+
+```Ruby
+api_map = Solargraph::ApiMap.new
+source = Solargraph::Source.load_string("var = 'a string'; puts var", 'example.rb')
+api_map.virtualize source
+fragment = source.fragment_at(0, 23)
+pins = api_map.define(fragment) # `var` is recognized as a local variable containing a String
+```
+
+## Querying Completion Suggestions
+```Ruby
+api_map = Solargraph::ApiMap.new
+source = Solargraph::Source.load_string("String.", 'example.rb')
+fragment = source.fragment_at(0, 7)
+completion = api_map.complete(fragment) # Suggestions will include String class methods
+```
+
+## Adding a Message to the Language Server Protocol
+
+```Ruby
+class MyMessage < Solargraph::LanguageServer::Message::Base
+  def process
+    STDERR.puts "Server received MyMessage with the following parameters: #{params}"
+  end
+end
+
+Solargraph::LanguageServer::Message.register '$/myMessage', MyMessage
+```
+
+## Adding a Diagnostics Reporter to the Language Server
+
+```Ruby
+class MyReporter < Solargraph::Diagnostics::Base
+  def diagnose source, api_map
+    # Return an array of hash objects that conform to the LSP's Diagnostic specification
+    []
+  end
+end
+
+Solargraph::Diagnostics.register 'my_reporter', MyReporter
+```
+
+## More Examples
+
+Developers are encouraged to refer to the specs for more examples of how to use Solargraph.

OVERVIEW.md

@@ -0,0 +1,33 @@
+# An Overview of Solargraph
+
+The Solargraph library consists of two major groups of components: the data providers and the language servers. The data providers manage the maps of information about a program. The language servers are the concrete implementations of transports and messages that enable the language server protocol.
+
+## Data Providers
+
+**ApiMap**: The component that provides information about a program based on its Workspace, external gems, and the Ruby core.
+
+**Workspace**: A collection of Sources that comprise a project. Workspaces have configurations that define which files to include in maps and other project-related options. Users can configure the Workspace through a .solargraph.yml file in a project's root directory.
+
+**Source**: Data about a single Ruby file. Sources parse Ruby code into an AST and generate a collection of Pins.
+
+**Pins**: Information about a class, a module, a method, a variable, etc. Most ApiMap queries return results as an array of Pins.
+
+**Fragment**: Information about a specific location in a Source. ApiMaps use fragments to gather contextual program data, such as local variables that are visible from the fragment's location or methods that are available within the location's scope.
+
+**YardMap**: A collection of YARD documents. ApiMaps use YardMaps to gather data from external gems and the Ruby core.
+
+**Library**: The component that synchronizes a Workspace with its associated ApiMap. Libraries help ensure that the ApiMap gets updated when a file in the Workspace changes.
+
+## Language Servers
+
+**Host**: The component responsible for processing messages between the server and the client. Hosts maintain a project's Library and provide thread-safe methods for asynchronous operations.
+
+**Messages**: Implementations of LSP methods and notifications.
+
+**Transports**: Server implementations for various protocols. The two transports that are currently supported are socket and stdio.
+
+## More Information
+
+The [EXAMPLES.md](EXAMPLES.md) document provides simple examples of how to use, extend, and modify the Solargraph library.
+
+Refer to [LANGUAGE_SERVER.md](LANGUAGE_SERVER.md) for information about connecting language clients to Solargraph language servers.