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
5package printer
6
7import (
8	"go/ast"
9	"go/doc/comment"
10	"strings"
11)
12
13// formatDocComment reformats the doc comment list,
14// returning the canonical formatting.
15func formatDocComment(list []*ast.Comment) []*ast.Comment {
16	// Extract comment text (removing comment markers).
17	var kind, text string
18	var directives []*ast.Comment
19	if len(list) == 1 && strings.HasPrefix(list[0].Text, "/*") {
20		kind = "/*"
21		text = list[0].Text
22		if !strings.Contains(text, "\n") || allStars(text) {
23			// Single-line /* .. */ comment in doc comment position,
24			// or multiline old-style comment like
25			//	/*
26			//	 * Comment
27			//	 * text here.
28			//	 */
29			// Should not happen, since it will not work well as a
30			// doc comment, but if it does, just ignore:
31			// reformatting it will only make the situation worse.
32			return list
33		}
34		text = text[2 : len(text)-2] // cut /* and */
35	} else if strings.HasPrefix(list[0].Text, "//") {
36		kind = "//"
37		var b strings.Builder
38		for _, c := range list {
39			after, found := strings.CutPrefix(c.Text, "//")
40			if !found {
41				return list
42			}
43			// Accumulate //go:build etc lines separately.
44			if isDirective(after) {
45				directives = append(directives, c)
46				continue
47			}
48			b.WriteString(strings.TrimPrefix(after, " "))
49			b.WriteString("\n")
50		}
51		text = b.String()
52	} else {
53		// Not sure what this is, so leave alone.
54		return list
55	}
56
57	if text == "" {
58		return list
59	}
60
61	// Parse comment and reformat as text.
62	var p comment.Parser
63	d := p.Parse(text)
64
65	var pr comment.Printer
66	text = string(pr.Comment(d))
67
68	// For /* */ comment, return one big comment with text inside.
69	slash := list[0].Slash
70	if kind == "/*" {
71		c := &ast.Comment{
72			Slash: slash,
73			Text:  "/*\n" + text + "*/",
74		}
75		return []*ast.Comment{c}
76	}
77
78	// For // comment, return sequence of // lines.
79	var out []*ast.Comment
80	for text != "" {
81		var line string
82		line, text, _ = strings.Cut(text, "\n")
83		if line == "" {
84			line = "//"
85		} else if strings.HasPrefix(line, "\t") {
86			line = "//" + line
87		} else {
88			line = "// " + line
89		}
90		out = append(out, &ast.Comment{
91			Slash: slash,
92			Text:  line,
93		})
94	}
95	if len(directives) > 0 {
96		out = append(out, &ast.Comment{
97			Slash: slash,
98			Text:  "//",
99		})
100		for _, c := range directives {
101			out = append(out, &ast.Comment{
102				Slash: slash,
103				Text:  c.Text,
104			})
105		}
106	}
107	return out
108}
109
110// isDirective reports whether c is a comment directive.
111// See go.dev/issue/37974.
112// This code is also in go/ast.
113func isDirective(c string) bool {
114	// "//line " is a line directive.
115	// "//extern " is for gccgo.
116	// "//export " is for cgo.
117	// (The // has been removed.)
118	if strings.HasPrefix(c, "line ") || strings.HasPrefix(c, "extern ") || strings.HasPrefix(c, "export ") {
119		return true
120	}
121
122	// "//[a-z0-9]+:[a-z0-9]"
123	// (The // has been removed.)
124	colon := strings.Index(c, ":")
125	if colon <= 0 || colon+1 >= len(c) {
126		return false
127	}
128	for i := 0; i <= colon+1; i++ {
129		if i == colon {
130			continue
131		}
132		b := c[i]
133		if !('a' <= b && b <= 'z' || '0' <= b && b <= '9') {
134			return false
135		}
136	}
137	return true
138}
139
140// allStars reports whether text is the interior of an
141// old-style /* */ comment with a star at the start of each line.
142func allStars(text string) bool {
143	for i := 0; i < len(text); i++ {
144		if text[i] == '\n' {
145			j := i + 1
146			for j < len(text) && (text[j] == ' ' || text[j] == '\t') {
147				j++
148			}
149			if j < len(text) && text[j] != '*' {
150				return false
151			}
152		}
153	}
154	return true
155}
156