Skip to content

Commit 6706931

Browse files
rscrsc
committed
go/doc: restore handling of multi-paragraph BUG comments
It was lost when the generic "Notes" support went in. Had to change the test setup, because it precluded even being able test multi-line comments, much less multi-paragraph comments. Now 'godoc sync/atomic' works correctly again. Fixes #6135. R=golang-dev, bradfitz CC=golang-dev https://golang.org/cl/13427045
1 parent 159c2b7 commit 6706931

11 files changed

+186
-45
lines changed

‎src/pkg/go/doc/doc_test.go

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ func readTemplate(filename string) *template.Template {
3232
t.Funcs(template.FuncMap{
3333
"node": nodeFmt,
3434
"synopsis": synopsisFmt,
35+
"indent": indentFmt,
3536
})
3637
return template.Must(t.ParseFiles(filepath.Join(dataDir, filename)))
3738
}
@@ -55,6 +56,15 @@ func synopsisFmt(s string) string {
5556
return "// " + strings.Replace(s, "\n", " ", -1)
5657
}
5758

59+
func indentFmt(indent, s string) string {
60+
end := ""
61+
if strings.HasSuffix(s, "\n") {
62+
end = "\n"
63+
s = s[:len(s)-1]
64+
}
65+
return indent + strings.Replace(s, "\n", "\n"+indent, -1) + end
66+
}
67+
5868
func isGoFile(fi os.FileInfo) bool {
5969
name := fi.Name()
6070
return !fi.IsDir() &&

‎src/pkg/go/doc/reader.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -414,7 +414,7 @@ func (r *reader) readNote(list []*ast.Comment) {
414414
// We remove any formatting so that we don't
415415
// get spurious line breaks/indentation when
416416
// showing the TODO body.
417-
body := clean(text[m[1]:])
417+
body := clean(text[m[1]:], keepNL)
418418
if body != "" {
419419
marker := text[m[2]:m[3]]
420420
r.notes[marker] = append(r.notes[marker], &Note{

‎src/pkg/go/doc/synopsis.go

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,20 @@ func firstSentenceLen(s string) int {
2727
return len(s)
2828
}
2929

30+
const (
31+
keepNL = 1 << iota
32+
)
33+
3034
// clean replaces each sequence of space, \n, \r, or \t characters
3135
// with a single space and removes any trailing and leading spaces.
32-
func clean(s string) string {
36+
// If the keepNL flag is set, newline characters are passed through
37+
// instead of being change to spaces.
38+
func clean(s string, flags int) string {
3339
var b []byte
3440
p := byte(' ')
3541
for i := 0; i < len(s); i++ {
3642
q := s[i]
37-
if q == '\n' || q == '\r' || q == '\t' {
43+
if (flags&keepNL) == 0 && q == '\n' || q == '\r' || q == '\t' {
3844
q = ' '
3945
}
4046
if q != ' ' || p != ' ' {
@@ -57,7 +63,7 @@ func clean(s string) string {
5763
// is the empty string.
5864
//
5965
func Synopsis(s string) string {
60-
s = clean(s[0:firstSentenceLen(s)])
66+
s = clean(s[0:firstSentenceLen(s)], 0)
6167
for _, prefix := range IllegalPrefixes {
6268
if strings.HasPrefix(strings.ToLower(s), prefix) {
6369
return ""

‎src/pkg/go/doc/testdata/a.0.golden

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,44 @@ FILENAMES
99
testdata/a1.go
1010

1111
BUGS .Bugs is now deprecated, please use .Notes instead
12-
// bug0
13-
// bug1
12+
bug0
13+
14+
bug1
15+
1416

1517
BUGS
16-
// bug0 (uid: uid)
17-
// bug1 (uid: uid)
18+
BUG(uid) bug0
19+
20+
BUG(uid) bug1
21+
1822

1923
NOTES
20-
// 1 of 4 - this is the first line of note 1 - note 1 continues on ... (uid: foo)
21-
// 2 of 4 (uid: foo)
22-
// 3 of 4 (uid: bar)
23-
// 4 of 4 - this is the last line of note 4 (uid: bar)
24-
// This note which contains a (parenthesized) subphrase must ... (uid: bam)
25-
// The ':' after the marker and uid is optional. (uid: xxx)
24+
NOTE(uid)
25+
26+
NOTE(foo) 1 of 4 - this is the first line of note 1
27+
- note 1 continues on this 2nd line
28+
- note 1 continues on this 3rd line
29+
30+
NOTE(foo) 2 of 4
31+
32+
NOTE(bar) 3 of 4
33+
34+
NOTE(bar) 4 of 4
35+
- this is the last line of note 4
36+
37+
NOTE(bam) This note which contains a (parenthesized) subphrase
38+
must appear in its entirety.
39+
40+
NOTE(xxx) The ':' after the marker and uid is optional.
41+
2642

2743
SECBUGS
28-
// sec hole 0 need to fix asap (uid: uid)
44+
SECBUG(uid) sec hole 0
45+
need to fix asap
46+
2947

3048
TODOS
31-
// todo0 (uid: uid)
32-
// todo1 (uid: uid)
49+
TODO(uid) todo0
50+
51+
TODO(uid) todo1
52+

‎src/pkg/go/doc/testdata/a.1.golden

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,44 @@ FILENAMES
99
testdata/a1.go
1010

1111
BUGS .Bugs is now deprecated, please use .Notes instead
12-
// bug0
13-
// bug1
12+
bug0
13+
14+
bug1
15+
1416

1517
BUGS
16-
// bug0 (uid: uid)
17-
// bug1 (uid: uid)
18+
BUG(uid) bug0
19+
20+
BUG(uid) bug1
21+
1822

1923
NOTES
20-
// 1 of 4 - this is the first line of note 1 - note 1 continues on ... (uid: foo)
21-
// 2 of 4 (uid: foo)
22-
// 3 of 4 (uid: bar)
23-
// 4 of 4 - this is the last line of note 4 (uid: bar)
24-
// This note which contains a (parenthesized) subphrase must ... (uid: bam)
25-
// The ':' after the marker and uid is optional. (uid: xxx)
24+
NOTE(uid)
25+
26+
NOTE(foo) 1 of 4 - this is the first line of note 1
27+
- note 1 continues on this 2nd line
28+
- note 1 continues on this 3rd line
29+
30+
NOTE(foo) 2 of 4
31+
32+
NOTE(bar) 3 of 4
33+
34+
NOTE(bar) 4 of 4
35+
- this is the last line of note 4
36+
37+
NOTE(bam) This note which contains a (parenthesized) subphrase
38+
must appear in its entirety.
39+
40+
NOTE(xxx) The ':' after the marker and uid is optional.
41+
2642

2743
SECBUGS
28-
// sec hole 0 need to fix asap (uid: uid)
44+
SECBUG(uid) sec hole 0
45+
need to fix asap
46+
2947

3048
TODOS
31-
// todo0 (uid: uid)
32-
// todo1 (uid: uid)
49+
TODO(uid) todo0
50+
51+
TODO(uid) todo1
52+

‎src/pkg/go/doc/testdata/a.2.golden

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,44 @@ FILENAMES
99
testdata/a1.go
1010

1111
BUGS .Bugs is now deprecated, please use .Notes instead
12-
// bug0
13-
// bug1
12+
bug0
13+
14+
bug1
15+
1416

1517
BUGS
16-
// bug0 (uid: uid)
17-
// bug1 (uid: uid)
18+
BUG(uid) bug0
19+
20+
BUG(uid) bug1
21+
1822

1923
NOTES
20-
// 1 of 4 - this is the first line of note 1 - note 1 continues on ... (uid: foo)
21-
// 2 of 4 (uid: foo)
22-
// 3 of 4 (uid: bar)
23-
// 4 of 4 - this is the last line of note 4 (uid: bar)
24-
// This note which contains a (parenthesized) subphrase must ... (uid: bam)
25-
// The ':' after the marker and uid is optional. (uid: xxx)
24+
NOTE(uid)
25+
26+
NOTE(foo) 1 of 4 - this is the first line of note 1
27+
- note 1 continues on this 2nd line
28+
- note 1 continues on this 3rd line
29+
30+
NOTE(foo) 2 of 4
31+
32+
NOTE(bar) 3 of 4
33+
34+
NOTE(bar) 4 of 4
35+
- this is the last line of note 4
36+
37+
NOTE(bam) This note which contains a (parenthesized) subphrase
38+
must appear in its entirety.
39+
40+
NOTE(xxx) The ':' after the marker and uid is optional.
41+
2642

2743
SECBUGS
28-
// sec hole 0 need to fix asap (uid: uid)
44+
SECBUG(uid) sec hole 0
45+
need to fix asap
46+
2947

3048
TODOS
31-
// todo0 (uid: uid)
32-
// todo1 (uid: uid)
49+
TODO(uid) todo0
50+
51+
TODO(uid) todo1
52+

‎src/pkg/go/doc/testdata/bugpara.0.golden

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
//
2+
PACKAGE bugpara
3+
4+
IMPORTPATH
5+
testdata/bugpara
6+
7+
FILENAMES
8+
testdata/bugpara.go
9+
10+
BUGS .Bugs is now deprecated, please use .Notes instead
11+
Sometimes bugs have multiple paragraphs.
12+
13+
Like this one.
14+
15+
16+
BUGS
17+
BUG(rsc) Sometimes bugs have multiple paragraphs.
18+
19+
Like this one.
20+

‎src/pkg/go/doc/testdata/bugpara.1.golden

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
//
2+
PACKAGE bugpara
3+
4+
IMPORTPATH
5+
testdata/bugpara
6+
7+
FILENAMES
8+
testdata/bugpara.go
9+
10+
BUGS .Bugs is now deprecated, please use .Notes instead
11+
Sometimes bugs have multiple paragraphs.
12+
13+
Like this one.
14+
15+
16+
BUGS
17+
BUG(rsc) Sometimes bugs have multiple paragraphs.
18+
19+
Like this one.
20+

‎src/pkg/go/doc/testdata/bugpara.2.golden

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
//
2+
PACKAGE bugpara
3+
4+
IMPORTPATH
5+
testdata/bugpara
6+
7+
FILENAMES
8+
testdata/bugpara.go
9+
10+
BUGS .Bugs is now deprecated, please use .Notes instead
11+
Sometimes bugs have multiple paragraphs.
12+
13+
Like this one.
14+
15+
16+
BUGS
17+
BUG(rsc) Sometimes bugs have multiple paragraphs.
18+
19+
Like this one.
20+

‎src/pkg/go/doc/testdata/bugpara.go

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
package bugpara
2+
3+
// BUG(rsc): Sometimes bugs have multiple paragraphs.
4+
//
5+
// Like this one.

‎src/pkg/go/doc/testdata/template.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ TYPES
6161

6262
*/}}{{with .Bugs}}
6363
BUGS .Bugs is now deprecated, please use .Notes instead
64-
{{range .}} {{synopsis .}}
64+
{{range .}}{{indent "\t" .}}
6565
{{end}}{{end}}{{with .Notes}}{{range $marker, $content := .}}
6666
{{$marker}}S
67-
{{range $content}} {{synopsis .Body}} (uid: {{.UID}})
67+
{{range $content}}{{$marker}}({{.UID}}){{indent "\t" .Body}}
6868
{{end}}{{end}}{{end}}

0 commit comments

Comments
 (0)