gopls/internal/lsp/protocol: include docs for {,Document}URI

The distinction between these types was not obvious to me.

Change-Id: I8ed19c0aff11c4918615e4b3d9d25895029e23c8
Reviewed-on: https://go-review.googlesource.com/c/tools/+/542315
Auto-Submit: Alan Donovan <[email protected]>
Reviewed-by: Robert Findley <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

gopls/internal/lsp/protocol/generate/output.go

@@ -239,8 +239,30 @@ func genStructs(model Model) {
 		types[nm] = out.String()
 	}
 	// base types
-	types["DocumentURI"] = "type DocumentURI string\n"
-	types["URI"] = "type URI = string\n"
+	types["DocumentURI"] = `
+// A DocumentURI is the URI of a client editor document.
+//
+// Care should be taken to handle encoding in URIs. For
+// example, some clients (such as VS Code) may encode colons
+// in drive letters while others do not. The URIs below are
+// both valid, but clients and servers should be consistent
+// with the form they use themselves to ensure the other party
+// doesn’t interpret them as distinct URIs. Clients and
+// servers should not assume that each other are encoding the
+// same way (for example a client encoding colons in drive
+// letters cannot assume server responses will have encoded
+// colons). The same applies to casing of drive letters - one
+// party should not assume the other party will return paths
+// with drive letters cased the same as it.
+//
+//    file:///c:/project/readme.md
+//    file:///C%3A/project/readme.md
+//
+type DocumentURI string
+`
+	types["URI"] = `// A URI is an arbitrary URL (e.g. https), not necessarily a file.
+type URI = string
+`
 
 	types["LSPAny"] = "type LSPAny = interface{}\n"
 	// A special case, the only previously existing Or type