doc_test.go

     1  // Copyright 2026 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 specgen
     6  
     7  import (
     8  	"testing"
     9  )
    10  
    11  func TestParseSpecDoc(t *testing.T) {
    12  	doc := `Add adds elements of
    13  x and y.
    14  
    15  	z[i] = x[i] + y[i]
    16  `
    17  	var root contextRoot
    18  	ctx := context{root: &root}
    19  	paras := parseSpecDoc(ctx, doc)
    20  	if err := root.gatherErrors(); err != nil {
    21  		t.Fatalf("unexpected error parsing spec doc: %v", err)
    22  	}
    23  
    24  	expected := []struct {
    25  		kind ParagraphKind
    26  		text string
    27  	}{
    28  		{SpecOwned, "Add adds elements of\nx and y."},
    29  		{SpecOwned, "\tz[i] = x[i] + y[i]"},
    30  	}
    31  	if len(paras) != len(expected) {
    32  		t.Fatalf("expected %d paragraphs, got %d", len(expected), len(paras))
    33  	}
    34  	for i, want := range expected {
    35  		if paras[i].Kind != want.kind {
    36  			t.Errorf("para %d: got kind %v, want %v", i, paras[i].Kind, want.kind)
    37  		}
    38  		if paras[i].Text != want.text {
    39  			t.Errorf("para %d: got text %q, want %q", i, paras[i].Text, want.text)
    40  		}
    41  	}
    42  
    43  	// Test FormatComment round-trip
    44  	formatted, err := FormatComment(paras)
    45  	if err != nil {
    46  		t.Fatalf("unexpected error formatting comment: %v", err)
    47  	}
    48  	wantFormatted := `// Add adds elements of
    49  // x and y.
    50  //
    51  //	z[i] = x[i] + y[i]
    52  `
    53  	if formatted != wantFormatted {
    54  		t.Errorf("FormatComment mismatch:\ngot:\n%s\nwant:\n%s", formatted, wantFormatted)
    55  	}
    56  }
    57  
    58  func TestParseSpecDocRejectsNotes(t *testing.T) {
    59  	doc := `Add adds elements.
    60  
    61  Asm: VPADDD`
    62  
    63  	var root contextRoot
    64  	ctx := context{root: &root}
    65  	_ = parseSpecDoc(ctx, doc)
    66  	if err := root.gatherErrors(); err == nil {
    67  		t.Fatalf("expected error for doc containing implementation note, got nil")
    68  	}
    69  }
    70  
    71  func TestFormatCommentOrdering(t *testing.T) {
    72  	tests := []struct {
    73  		name    string
    74  		paras   []Paragraph
    75  		wantErr bool
    76  	}{
    77  		{
    78  			name: "valid order",
    79  			paras: []Paragraph{
    80  				{Kind: SpecOwned, Text: "Spec\n"},
    81  				{Kind: ImplementationNote, Text: "Asm: VFOO\n"},
    82  				{Kind: DirectiveComment, Text: "go:noescape\n"},
    83  			},
    84  			wantErr: false,
    85  		},
    86  		{
    87  			name: "spec owned after note",
    88  			paras: []Paragraph{
    89  				{Kind: ImplementationNote, Text: "Asm: VFOO\n"},
    90  				{Kind: SpecOwned, Text: "Spec\n"},
    91  			},
    92  			wantErr: true,
    93  		},
    94  		{
    95  			name: "spec owned after directive",
    96  			paras: []Paragraph{
    97  				{Kind: DirectiveComment, Text: "go:noescape\n"},
    98  				{Kind: SpecOwned, Text: "Spec\n"},
    99  			},
   100  			wantErr: true,
   101  		},
   102  		{
   103  			name: "note after directive",
   104  			paras: []Paragraph{
   105  				{Kind: DirectiveComment, Text: "go:noescape\n"},
   106  				{Kind: ImplementationNote, Text: "Asm: VFOO\n"},
   107  			},
   108  			wantErr: true,
   109  		},
   110  	}
   111  
   112  	for _, tc := range tests {
   113  		t.Run(tc.name, func(t *testing.T) {
   114  			_, err := FormatComment(tc.paras)
   115  			if (err != nil) != tc.wantErr {
   116  				t.Errorf("FormatComment() error = %v, wantErr %v", err, tc.wantErr)
   117  			}
   118  		})
   119  	}
   120  }
   121
View as plain text