fix(internal/lsp): 修正 textDocument/hover 在空值是返回 {} 而不是 null 的错误

internal/lsp/protocol/enums.go

@@ -119,8 +119,8 @@ const (
 	// MarkupKindPlainText plain text is supported as a content format
 	MarkupKindPlainText MarkupKind = "plaintext"
 
-	// MarkupKinMarkdown markdown is supported as a content format
-	MarkupKinMarkdown MarkupKind = "markdown"
+	// MarkupKindMarkdown markdown is supported as a content format
+	MarkupKindMarkdown MarkupKind = "markdown"
 )
 
 // TextDocumentSyncKind defines how the host (editor) should sync document changes to the language server.

internal/lsp/protocol/hover.go

@@ -2,7 +2,11 @@
 
 package protocol
 
-import "github.com/caixw/apidoc/v7/core"
+import (
+	"encoding/json"
+
+	"github.com/caixw/apidoc/v7/core"
+)
 
 // HoverCapabilities 客户端有关 hover 功能的描述
 type HoverCapabilities struct {
@@ -24,9 +28,21 @@ type HoverParams struct {
 type Hover struct {
 	// The hover's content
 	// contents MarkedString | MarkedString[] | MarkupContent;
-	Contents interface{} `json:"contents"`
+	Contents MarkupContent `json:"contents"`
 
 	// An optional range is a range inside a text document
 	// that is used to visualize a hover, e.g. by changing the background color.
 	Range core.Range `json:"range,omitempty"`
 }
+
+type hoverShadow Hover
+
+// MarshalJSON 允许在 hover 为空值是返回 null
+func (h *Hover) MarshalJSON() ([]byte, error) {
+	if h.Contents.Kind == "" {
+		return json.Marshal(nil)
+	}
+
+	shadow := (*hoverShadow)(h)
+	return json.Marshal(shadow)
+}

internal/lsp/search/hover.go

@@ -22,12 +22,16 @@ var usagerType = reflect.TypeOf((*usager)(nil)).Elem()
 // 返回值表示是否找到了相应在的元素。
 func Hover(doc *ast.APIDoc, uri core.URI, pos core.Position, h *protocol.Hover) {
 	u := doc.Search(uri, pos, usagerType)
-	if u != nil {
-		usage := u.(usager)
+	if u == nil {
+		return
+	}
+
+	usage := u.(usager)
+	if v := usage.Usage(); v != "" {
 		h.Range = usage.R()
 		h.Contents = protocol.MarkupContent{
-			Kind:  protocol.MarkupKinMarkdown,
-			Value: usage.Usage(),
+			Kind:  protocol.MarkupKindMarkdown,
+			Value: v,
 		}
 	}
 }

internal/lsp/search/hover_test.go

@@ -45,7 +45,7 @@ func TestHover(t *testing.T) {
 		Start: core.Position{Line: 1, Character: 1},
 		End:   core.Position{Line: 1, Character: 18},
 	})
-	a.Equal(hover.Contents.(protocol.MarkupContent).Value, locale.Sprintf("usage-apidoc-title"))
+	a.Equal(hover.Contents.Value, locale.Sprintf("usage-apidoc-title"))
 
 	// apis[0]
 	hover = &protocol.Hover{}
@@ -55,7 +55,7 @@ func TestHover(t *testing.T) {
 		Start: core.Position{Line: 4, Character: 1},
 		End:   core.Position{Line: 7, Character: 7},
 	})
-	a.Equal(hover.Contents.(protocol.MarkupContent).Value, locale.Sprintf("usage-apidoc-apis"))
+	a.Equal(hover.Contents.Value, locale.Sprintf("usage-apidoc-apis"))
 
 	// 改变了 api[0].URI
 	doc.APIs[0].URI = core.URI("api0.go")
@@ -68,7 +68,7 @@ func TestHover(t *testing.T) {
 		Start: core.Position{Line: 0, Character: 0},
 		End:   core.Position{Line: 12, Character: 9},
 	})
-	a.Equal(hover.Contents.(protocol.MarkupContent).Value, locale.Sprintf("usage-apidoc"))
+	a.Equal(hover.Contents.Value, locale.Sprintf("usage-apidoc"))
 
 	// 与 apis[0] 相同的 URI
 	hover = &protocol.Hover{}
@@ -78,5 +78,5 @@ func TestHover(t *testing.T) {
 		Start: core.Position{Line: 4, Character: 1},
 		End:   core.Position{Line: 7, Character: 7},
 	})
-	a.Equal(hover.Contents.(protocol.MarkupContent).Value, locale.Sprintf("usage-apidoc-apis"))
+	a.Equal(hover.Contents.Value, locale.Sprintf("usage-apidoc-apis"))
 }

internal/xmlenc/xmlenc.go

@@ -31,6 +31,10 @@ type BaseTag struct {
 
 // Usage 本地化的当前字段介绍内容
 func (b Base) Usage() string {
+	if b.UsageKey == nil {
+		return ""
+	}
+
 	return locale.Sprintf(b.UsageKey)
 }
 

internal/xmlenc/xmlenc_test.go

@@ -6,6 +6,8 @@ import (
 	"testing"
 
 	"github.com/issue9/assert"
+
+	"github.com/caixw/apidoc/v7/internal/locale"
 )
 
 func TestBaseTag_SelfClose(t *testing.T) {
@@ -26,3 +28,13 @@ func TestBaseTag_SelfClose(t *testing.T) {
 	}
 	a.False(b.SelfClose())
 }
+
+func TestBase_Usage(t *testing.T) {
+	a := assert.New(t)
+
+	b := Base{}
+	a.Empty(b.Usage())
+
+	b.UsageKey = locale.ErrInvalidUTF8Character
+	a.Equal(b.Usage(), locale.Sprintf(locale.ErrInvalidUTF8Character))
+}