gopls/internal/test/marker: minor clean up of marker test doc

Change-Id: Id5fd8592a207e8ade8aeb1521730e4f35514824e
Reviewed-on: https://go-review.googlesource.com/c/tools/+/549120
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Robert Findley <rfindley@google.com>

gopls/internal/test/marker/doc.go

@@ -33,35 +33,14 @@ which is extracted to a temporary directory. The relative path to the .txt
 file is used as the subtest name. The preliminary section of the file
 (before the first archive entry) is a free-form comment.
 
-These tests were inspired by (and in many places copied from) a previous
-iteration of the marker tests built on top of the packagestest framework.
-Key design decisions motivating this reimplementation are as follows:
-  - The old tests had a single global session, causing interaction at a
-    distance and several awkward workarounds.
-  - The old tests could not be safely parallelized, because certain tests
-    manipulated the server options
-  - Relatedly, the old tests did not have a logic grouping of assertions into
-    a single unit, resulting in clusters of files serving clusters of
-    entangled assertions.
-  - The old tests used locations in the source as test names and as the
-    identity of golden content, meaning that a single edit could change the
-    name of an arbitrary number of subtests, and making it difficult to
-    manually edit golden content.
-  - The old tests did not hew closely to LSP concepts, resulting in, for
-    example, each marker implementation doing its own position
-    transformations, and inventing its own mechanism for configuration.
-  - The old tests had an ad-hoc session initialization process. The integration
-    test environment has had more time devoted to its initialization, and has a
-    more convenient API.
-  - The old tests lacked documentation, and often had failures that were hard
-    to understand. By starting from scratch, we can revisit these aspects.
-
 # Special files
 
 There are several types of file within the test archive that are given special
 treatment by the test runner:
+
   - "skip": the presence of this file causes the test to be skipped, with
     the file content used as the skip message.
+
   - "flags": this file is treated as a whitespace-separated list of flags
     that configure the MarkerTest instance. Supported flags:
     -min_go=go1.20 sets the minimum Go version for the test;
@@ -78,21 +57,28 @@ treatment by the test runner:
     -filter_keywords=false disables the filtering of keywords from
     completion results.
     TODO(rfindley): support flag values containing whitespace.
+
   - "settings.json": this file is parsed as JSON, and used as the
     session configuration (see gopls/doc/settings.md)
+
   - "capabilities.json": this file is parsed as JSON client capabilities,
     and applied as an overlay over the default editor client capabilities.
     see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#clientCapabilities
     for more details.
+
   - "env": this file is parsed as a list of VAR=VALUE fields specifying the
     editor environment.
+
   - Golden files: Within the archive, file names starting with '@' are
     treated as "golden" content, and are not written to disk, but instead are
     made available to test methods expecting an argument of type *Golden,
     using the identifier following '@'. For example, if the first parameter of
     Foo were of type *Golden, the test runner would convert the identifier a
     in the call @foo(a, "b", 3) into a *Golden by collecting golden file
-    data starting with "@a/".
+    data starting with "@a/". As a special case, for tests that only need one
+    golden file, the data contained in the file "@a" is indexed in the *Golden
+    value by the empty string "".
+
   - proxy files: any file starting with proxy/ is treated as a Go proxy
     file. If present, these files are written to a separate temporary
     directory and GOPROXY is set to file://<proxy directory>.
@@ -309,11 +295,14 @@ parameter type pairs:
 
 Here is a complete example:
 
+	This test checks hovering over constants.
+
 	-- a.go --
 	package a
 
 	const abc = 0x2a //@hover("b", "abc", abc),hover(" =", "abc", abc)
-	-- @abc/hover.md --
+
+	-- @abc --
 	```go
 	const abc untyped int = 42
 	```
@@ -329,13 +318,13 @@ The first argument holds the test context, including fake editor with open
 files, and sandboxed directory.
 
 Argument converters translate the "b" and "abc" arguments into locations by
-interpreting each one as a regular expression and finding the location of
-its first match on the preceding portion of the line, and the abc identifier
-into a dictionary of golden content containing "hover.md". Then the
-hoverMarker method executes a textDocument/hover LSP request at the src
-position, and ensures the result spans "abc", with the markdown content from
-hover.md. (Note that the markdown content includes the expect annotation as
-the doc comment.)
+interpreting each one as a substring (or as a regular expression, if of the
+form re"a|b") and finding the location of its first occurrence on the preceding
+portion of the line, and the abc identifier into a the golden content contained
+in the file @abc. Then the hoverMarker method executes a textDocument/hover LSP
+request at the src position, and ensures the result spans "abc", with the
+markdown content from @abc. (Note that the markdown content includes the expect
+annotation as the doc comment.)
 
 The next hover on the same line asserts the same result, but initiates the
 hover immediately after "abc" in the source. This tests that we find the

gopls/internal/test/marker/marker_test.go

@@ -59,6 +59,29 @@ func TestMain(m *testing.M) {
 // Test runs the marker tests from the testdata directory.
 //
 // See package documentation for details on how marker tests work.
+//
+// These tests were inspired by (and in many places copied from) a previous
+// iteration of the marker tests built on top of the packagestest framework.
+// Key design decisions motivating this reimplementation are as follows:
+//   - The old tests had a single global session, causing interaction at a
+//     distance and several awkward workarounds.
+//   - The old tests could not be safely parallelized, because certain tests
+//     manipulated the server options
+//   - Relatedly, the old tests did not have a logic grouping of assertions into
+//     a single unit, resulting in clusters of files serving clusters of
+//     entangled assertions.
+//   - The old tests used locations in the source as test names and as the
+//     identity of golden content, meaning that a single edit could change the
+//     name of an arbitrary number of subtests, and making it difficult to
+//     manually edit golden content.
+//   - The old tests did not hew closely to LSP concepts, resulting in, for
+//     example, each marker implementation doing its own position
+//     transformations, and inventing its own mechanism for configuration.
+//   - The old tests had an ad-hoc session initialization process. The integration
+//     test environment has had more time devoted to its initialization, and has a
+//     more convenient API.
+//   - The old tests lacked documentation, and often had failures that were hard
+//     to understand. By starting from scratch, we can revisit these aspects.
 func Test(t *testing.T) {
 	// The marker tests must be able to run go/packages.Load.
 	testenv.NeedsGoPackages(t)