comment.go

     1  // Copyright 2009 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  package doc
     6  
     7  import (
     8  	"go/doc/comment"
     9  	"io"
    10  )
    11  
    12  // ToHTML converts comment text to formatted HTML.
    13  //
    14  // Deprecated: ToHTML cannot identify documentation links
    15  // in the doc comment, because they depend on knowing what
    16  // package the text came from, which is not included in this API.
    17  //
    18  // Given the *[doc.Package] p where text was found,
    19  // ToHTML(w, text, nil) can be replaced by:
    20  //
    21  //	w.Write(p.HTML(text))
    22  //
    23  // which is in turn shorthand for:
    24  //
    25  //	w.Write(p.Printer().HTML(p.Parser().Parse(text)))
    26  //
    27  // If words may be non-nil, the longer replacement is:
    28  //
    29  //	parser := p.Parser()
    30  //	parser.Words = words
    31  //	w.Write(p.Printer().HTML(parser.Parse(d)))
    32  func ToHTML(w io.Writer, text string, words map[string]string) {
    33  	p := new(Package).Parser()
    34  	p.Words = words
    35  	d := p.Parse(text)
    36  	pr := new(comment.Printer)
    37  	w.Write(pr.HTML(d))
    38  }
    39  
    40  // ToText converts comment text to formatted text.
    41  //
    42  // Deprecated: ToText cannot identify documentation links
    43  // in the doc comment, because they depend on knowing what
    44  // package the text came from, which is not included in this API.
    45  //
    46  // Given the *[doc.Package] p where text was found,
    47  // ToText(w, text, "", "\t", 80) can be replaced by:
    48  //
    49  //	w.Write(p.Text(text))
    50  //
    51  // In the general case, ToText(w, text, prefix, codePrefix, width)
    52  // can be replaced by:
    53  //
    54  //	d := p.Parser().Parse(text)
    55  //	pr := p.Printer()
    56  //	pr.TextPrefix = prefix
    57  //	pr.TextCodePrefix = codePrefix
    58  //	pr.TextWidth = width
    59  //	w.Write(pr.Text(d))
    60  //
    61  // See the documentation for [Package.Text] and [comment.Printer.Text]
    62  // for more details.
    63  func ToText(w io.Writer, text string, prefix, codePrefix string, width int) {
    64  	d := new(Package).Parser().Parse(text)
    65  	pr := &comment.Printer{
    66  		TextPrefix:     prefix,
    67  		TextCodePrefix: codePrefix,
    68  		TextWidth:      width,
    69  	}
    70  	w.Write(pr.Text(d))
    71  }
    72
View as plain text