golang.org/x/tools/gopls@v0.15.3/internal/golang/comment_go119.go (about)

     1  // Copyright 2022 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:build go1.19
     6  // +build go1.19
     7  
     8  package golang
     9  
    10  // Starting with go1.19, the formatting of comments has changed, and there
    11  // is a new package (go/doc/comment) for processing them.
    12  // As long as gopls has to compile under earlier versions, tests
    13  // have to pass with both the old and new code, which produce
    14  // slightly different results.
    15  
    16  // When gopls no longer needs to compile with go1.18, the old comment.go should
    17  // be replaced by this file, the golden test files should be updated.
    18  // (and checkSameMarkdown() could be replaced by a simple comparison.)
    19  
    20  import (
    21  	"fmt"
    22  	"go/doc/comment"
    23  
    24  	"golang.org/x/tools/gopls/internal/settings"
    25  )
    26  
    27  // CommentToMarkdown converts comment text to formatted markdown.
    28  // The comment was prepared by DocReader,
    29  // so it is known not to have leading, trailing blank lines
    30  // nor to have trailing spaces at the end of lines.
    31  // The comment markers have already been removed.
    32  func CommentToMarkdown(text string, options *settings.Options) string {
    33  	var p comment.Parser
    34  	doc := p.Parse(text)
    35  	var pr comment.Printer
    36  	// The default produces {#Hdr-...} tags for headings.
    37  	// vscode displays thems, which is undesirable.
    38  	// The godoc for comment.Printer says the tags
    39  	// avoid a security problem.
    40  	pr.HeadingID = func(*comment.Heading) string { return "" }
    41  	pr.DocLinkURL = func(link *comment.DocLink) string {
    42  		msg := fmt.Sprintf("https://%s/%s", options.LinkTarget, link.ImportPath)
    43  		if link.Name != "" {
    44  			msg += "#"
    45  			if link.Recv != "" {
    46  				msg += link.Recv + "."
    47  			}
    48  			msg += link.Name
    49  		}
    50  		return msg
    51  	}
    52  	easy := pr.Markdown(doc)
    53  	return string(easy)
    54  }