internal/lsp/regtest: add expository package documentation

Update the regtest docstring to further explain how the package works,
and give a sense for why it exists.

Fixes golang/go#36879

Change-Id: I4df4a286dc835ae56386b6d92128f7ea6c77ffb0
Reviewed-on: https://go-review.googlesource.com/c/tools/+/229782
Run-TryBot: Robert Findley <rfindley@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rebecca Stambler <rstambler@golang.org>

internal/lsp/regtest/doc.go

@@ -0,0 +1,36 @@
+// Copyright 2020 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package regtest provides a framework for writing gopls regression tests.
+//
+// User reported regressions are often expressed in terms of editor
+// interactions. For example: "When I open my editor in this directory,
+// navigate to this file, and change this line, I get a diagnostic that doesn't
+// make sense". In these cases reproducing, diagnosing, and writing a test to
+// protect against this regression can be difficult.
+//
+// The regtest package provides an API for developers to express these types of
+// user interactions in ordinary Go tests, validate them, and run them in a
+// variety of execution modes (see gopls/doc/daemon.md for more information on
+// execution modes). This is achieved roughly as follows:
+//  + the Runner type starts and connects to a gopls instance for each
+//    configured execution mode.
+//  + the Env type provides a collection of resources to use in writing tests
+//    (for example a temporary working directory and fake text editor)
+//  + user interactions with these resources are scripted using test wrappers
+//    around the API provided by the golang.org/x/tools/internal/lsp/fake
+//    package.
+//
+// Regressions are expressed in terms of Expectations, which at a high level
+// are conditions that we expect to be met (or not to be met) at some point
+// after performing the interactions in the test. This is necessary because the
+// LSP is by construction asynchronous: both client and server can send
+// eachother notifications without formal acknowledgement that they have been
+// fully processed.
+//
+// Simple Expectations may be combined to match specific conditions reported by
+// the user. In the example above, a regtest validating that the user-reported
+// bug had been fixed would "expect" that the editor never displays the
+// confusing diagnostic.
+package regtest

internal/lsp/regtest/env.go

@@ -2,7 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package regtest provides an environment for writing regression tests.
 package regtest
 
 import (