feat(codeintel): If SignatureDocumentation is present in SCIP, use it for hover text

internal/codeintel/codenav/internal/lsifstore/locations_by_position.go

@@ -283,7 +283,7 @@ func extractOccurrenceData(document *scip.Document, occurrence *scip.Occurrence)
 	// we should include in reference and implementation searches.
 
 	if symbol := scip.FindSymbol(document, occurrence.Symbol); symbol != nil {
-		hoverText = symbol.Documentation
+		hoverText = symbolHoverText(symbol)
 
 		for _, rel := range symbol.Relationships {
 			if rel.IsDefinition {
@@ -366,8 +366,13 @@ func monikersToString(vs []precise.MonikerData) string {
 	return strings.Join(strs, ", ")
 }
 
-//
-//
+func symbolHoverText(symbol *scip.SymbolInformation) []string {
+	if sigdoc := symbol.SignatureDocumentation; sigdoc != nil && sigdoc.Text != "" && sigdoc.Language != "" {
+		signature := []string{fmt.Sprintf("```%s\n%s\n```", sigdoc.Language, sigdoc.Text)}
+		return append(signature, symbol.Documentation...)
+	}
+	return symbol.Documentation
+}
 
 func (s *store) ExtractDefinitionLocationsFromPosition(ctx context.Context, locationKey LocationKey) (_ []shared.Location, _ []string, err error) {
 	return s.extractLocationsFromPosition(ctx, extractDefinitionRanges, symbolExtractDefault, s.operations.getDefinitionLocations, locationKey)

internal/codeintel/codenav/internal/lsifstore/locations_by_position_test.go

@@ -556,6 +556,90 @@ func TestExtractOccurrenceData(t *testing.T) {
 		}
 	})
 
+	t.Run("documentation and signature documentation", func(t *testing.T) {
+		testCases := []struct {
+			explanation string
+			document    *scip.Document
+			occurrence  *scip.Occurrence
+			hoverText   []string
+		}{
+			{
+				explanation: "#1 backwards compatibility: SignatureDocumentation is absent, Documentation is present",
+				document: &scip.Document{
+					Symbols: []*scip.SymbolInformation{
+						{
+							Symbol: "react 17.1 main.go func1",
+							Documentation: []string{
+								"```go\nfunc1()\n```",
+								"it does the thing",
+							},
+						},
+					},
+				},
+				occurrence: &scip.Occurrence{
+					Symbol:      "react 17.1 main.go func1",
+					SymbolRoles: 1,
+				},
+				hoverText: []string{
+					"```go\nfunc1()\n```",
+					"it does the thing",
+				},
+			},
+			{
+				explanation: "#2: SignatureDocumentation is present",
+				document: &scip.Document{
+					Symbols: []*scip.SymbolInformation{
+						{
+							Symbol: "react 17.1 main.go func1",
+							SignatureDocumentation: &scip.Document{
+								Language: "go",
+								Text:     "func1()",
+							},
+							Documentation: []string{
+								"it does the thing",
+							},
+						},
+					},
+				},
+				occurrence: &scip.Occurrence{
+					Symbol:      "react 17.1 main.go func1",
+					SymbolRoles: 1,
+				},
+				hoverText: []string{
+					"```go\nfunc1()\n```",
+					"it does the thing",
+				},
+			},
+			{
+				explanation: "#3: SignatureDocumentation is present, but Text/Language are empty",
+				document: &scip.Document{
+					Symbols: []*scip.SymbolInformation{
+						{
+							Symbol:                 "react 17.1 main.go func1",
+							SignatureDocumentation: &scip.Document{},
+							Documentation: []string{
+								"it does the thing",
+							},
+						},
+					},
+				},
+				occurrence: &scip.Occurrence{
+					Symbol:      "react 17.1 main.go func1",
+					SymbolRoles: 1,
+				},
+				hoverText: []string{
+					"it does the thing",
+				},
+			},
+		}
+
+		for _, testCase := range testCases {
+			if diff := cmp.Diff(testCase.hoverText, extractOccurrenceData(testCase.document, testCase.occurrence).hoverText); diff != "" {
+				t.Errorf("unexpected documentation (-want +got):\n%s -- %s", diff, testCase.explanation)
+			}
+		}
+	})
+
 	t.Run("implementations", func(t *testing.T) {
 		testCases := []struct {
 			explanation    string

internal/codeintel/codenav/internal/lsifstore/metadata_by_position.go

@@ -94,7 +94,7 @@ func (s *store) GetHover(ctx context.Context, bundleID int, path string, line, c
 				}
 
 				// Return first match
-				return strings.Join(symbol.Documentation, "\n"), rangeBySymbol[symbolName], true, nil
+				return strings.Join(symbolHoverText(symbol), "\n"), rangeBySymbol[symbolName], true, nil
 			}
 		}
 	}