basic: update Position documentation

Signed-off-by: Koichi Shiraishi <[email protected]>

Author: zchee

basic.go

@@ -28,14 +28,24 @@ var EOL = []string{"\n", "\r\n", "\r"}
 
 // Position represents a text document expressed as zero-based line and zero-based character offset.
 //
+// The offsets are based on a UTF-16 string representation.
+// So a string of the form "a𐐀b" the character offset of the character "a" is 0,
+// the character offset of "𐐀" is 1 and the character offset of "b" is 3 since 𐐀 is represented using two code units in UTF-16.
+//
+// To ensure that both client and server split the string into the same line representation the protocol
+// specifies the following end-of-line sequences: "\n", "\r\n' and "\r".
+//
 // A position is between two characters like an "insert" cursor in a editor.
+// Special values like for example "-1" to denote the end of a line are not supported.
 type Position struct {
 	// Line position in a document (zero-based).
 	Line uint32 `json:"line"`
 
-	// Character offset on a line in a document (zero-based). Assuming that the line is
-	// represented as a string, the `character` value represents the gap between the
-	// `character` and `character + 1`.
+	// Character offset on a line in a document (zero-based).
+	//
+	// Assuming that the line is represented as a string, the "character" value represents the gap between the
+	// "character" and "character + 1".
+	//
 	// If the character value is greater than the line length it defaults back to the
 	// line length.
 	Character uint32 `json:"character"`