Bump version and slightly improve doc

* eglot.el: Bump version. Add nicer Commentary header.
(eglot): Improve docstring.

* README.md: Update

README.md

@@ -4,10 +4,10 @@ Eglot
 
 *E*macs Poly*glot*. An Emacs client to [Language Server Protocol][lsp] servers.
 
-```
-(add-to-list 'load-path "/path/to/eglot")
-(require 'eglot) ; Requires emacs 26!
+Eglot is [in ELPA][gnuelpa]. Installation is straightforward:
 
+```
+(package-install 'eglot) ; Requires Emacs 26!
 ;; Now find some source file, any source file
 M-x eglot
 ```
@@ -22,7 +22,7 @@ for the language of your choice. Otherwise, it prompts you to enter one:
 * Python's [pyls][pyls]
 * Bash's [bash-language-server][bash-language-server]
 
-I'll add more as I test more features. In the meantime you can
+I'll add to this list as I test more servers. In the meantime you can
 customize `eglot-server-programs`:
 
 ```lisp
@@ -41,7 +41,9 @@ Here's a summary of available commands:
 
 - `M-x eglot-reconnect` reconnects to the server;
 
-- `M-x eglot-rename` asks the server to rename the symbol at point
+- `M-x eglot-shutdown` says bye-bye to the server;
+
+- `M-x eglot-rename` asks the server to rename the symbol at point;
 
 - `M-x eglot-help-at-point` asks the server for help for symbol at
   point. Currently this is what `eldoc-mode` displays in the echo
@@ -60,6 +62,23 @@ either:
 (define-key eglot-mode-map (kbd "<f6>") 'xref-find-definitions)
 ```
 
+# How does this work exactly?
+
+`M-x eglot` starts a server via a shell-command guessed from
+`eglot-server-programs`, using the current major-mode (for whatever
+language you're programming in) as a hint.
+
+If the connection is successful, you see an `[eglot:<server>]`
+indicator pop up in your mode-line.  More importantly, this means
+current *and future* file buffers of that major mode *inside your
+current project* automatically become \"managed\" by the LSP server,
+i.e.  information about their contents is exchanged periodically to
+provide enhanced code analysis via `xref-find-definitions`,
+`flymake-mode`, `eldoc-mode`, `completion-at-point`, among others.
+
+To "unmanage" these buffers, shutdown the server with `M-x
+eglot-shutdown`.
+
 # Supported Protocol features (3.6)
 
 ## General
@@ -104,7 +123,7 @@ either:
 - [x] textDocument/completion
 - [x] completionItem/resolve (works quite well with [company-mode][company-mode])
 - [x] textDocument/hover
-- [x] textDocument/signatureHelp (fancy stuff with Python's [pyls[pyls]])
+- [x] textDocument/signatureHelp (fancy stuff with Python's [pyls][pyls])
 - [x] textDocument/definition
 - [ ] textDocument/typeDefinition (3.6.0)
 - [ ] textDocument/implementation (3.6.0)
@@ -152,7 +171,7 @@ User-visible differences:
 
 Under the hood:
 
-- Message parser is much much simpler.
+- Message parser is much simpler.
 - Defers signature requests like `textDocument/hover` until server is
   ready. Also sends `textDocument/didChange` for groups of edits, not
   one per each tiny change.
@@ -169,6 +188,7 @@ Under the hood:
 [lsp]: https://microsoft.github.io/language-server-protocol/
 [rls]: https://github.com/rust-lang-nursery/rls
 [pyls]: https://github.com/palantir/python-language-server
+[gnuelpa]: https://elpa.gnu.org/packages/eglot.html
 [javascript-typescript-langserver]: https://github.com/sourcegraph/javascript-typescript-langserver
 [emacs-lsp]: https://github.com/emacs-lsp/lsp-mode
 [emacs-lsp-plugins]: https://github.com/emacs-lsp

eglot.el

@@ -2,7 +2,7 @@
 
 ;; Copyright (C) 2018 Free Software Foundation, Inc.
 
-;; Version: 0.1
+;; Version: 0.2
 ;; Author: João Távora <[email protected]>
 ;; Maintainer: João Távora <[email protected]>
 ;; URL: https://github.com/joaotavora/eglot
@@ -24,8 +24,28 @@
 
 ;;; Commentary:
 
-;; Simply M-x eglot should be enough to get you started, but see README.md.
-
+;; Simply M-x eglot should be enough to get you started, but here's a
+;; little info (see the accompanying README.md or the URL for more).
+;;
+;; M-x eglot starts a server via a shell-command guessed from
+;; `eglot-server-programs', using the current major-mode (for whatever
+;; language you're programming in) as a hint.  If it can't guess, it
+;; prompts you in the mini-buffer for these things.  Actually, the
+;; server needen't be locally started: you can connect to a running
+;; server via TCP by entering a <host:port> syntax.
+;;
+;; Anyway, if the connection is successful, you should see an `eglot'
+;; indicator pop up in your mode-line.  More importantly, this means
+;; current *and future* file buffers of that major mode *inside your
+;; current project* automatically become \"managed\" by the LSP
+;; server, i.e.  information about their contents is exchanged
+;; periodically to provide enhanced code analysis via
+;; `xref-find-definitions', `flymake-mode', `eldoc-mode',
+;; `completion-at-point', among others.
+;;
+;; To "unmanage" these buffers, shutdown the server with M-x
+;; eglot-shutdown.
+;;
 ;;; Code:
 
 (require 'json)
@@ -314,9 +334,22 @@ INTERACTIVE is t if inside interactive call."
 
 ;;;###autoload
 (defun eglot (managed-major-mode project command &optional interactive)
-  "Start a Language Server Protocol server.
-Server is started with COMMAND and manages buffers of
-MANAGED-MAJOR-MODE for the current project.
+  "Manage a project with a Language Server Protocol (LSP) server.
+
+The LSP server is started (or contacted) via COMMAND.  If this
+operation is successful, current *and future* file buffers of
+MANAGED-MAJOR-MODE inside PROJECT automatically become
+\"managed\" by the LSP server, meaning information about their
+contents is exchanged periodically to provide enhanced
+code-analysis via `xref-find-definitions', `flymake-mode',
+`eldoc-mode', `completion-at-point', among others.
+
+Interactively, the command attempts to guess MANAGED-MAJOR-MODE
+from current buffer, COMMAND from `eglot-server-programs' and
+PROJECT from `project-current'.  If it can't guess, the user is
+prompted.  With a single \\[universal-argument] prefix arg, it
+always prompt for COMMAND.  With two \\[universal-argument]
+prefix args, also prompts for MANAGED-MAJOR-MODE.
 
 PROJECT is a project instance as returned by `project-current'.
 
@@ -328,12 +361,6 @@ is also know as the server's \"contact\".
 
 MANAGED-MAJOR-MODE is an Emacs major mode.
 
-Interactively, guess MANAGED-MAJOR-MODE from current buffer and
-COMMAND from `eglot-server-programs'.  With a single
-\\[universal-argument] prefix arg, prompt for COMMAND.  With two
-\\[universal-argument] prefix args, also prompt for
-MANAGED-MAJOR-MODE.
-
 INTERACTIVE is t if called interactively."
   (interactive (eglot--interactive))
   (let* ((short-name (eglot--project-short-name project)))